SWire Documentation
A Stata plugin for connecting Stata with other software
Brought to you by:
lo-magno
SWire 0.2 - HTTPS
Home | SWire 0.2 documentation
HTTPS
The SWire server can also run in HTTPS mode. HTTPS is a communication protocol which ensures authentication of the server and privacy of the exchanged data. HTTPS servers require a private key and a public key, both of which are used for encryption and decryption in the communication process with the client. The public key is embedded in a public Certificate which identifies a subject (e.g.: the server). During data exchange, the public Certificate is sent to the client, while the private key is kept secret. The public Certificate may be signed by a Certification Authority or it may be self-signed. By signing a Certificate, the Certification Authority certifies the identity of the subject to which the Certificate refers. The Certification Authority is also identified by a public Certificate.
The SWire HTTPS server requires a private key and a public Certificate; the latter identifies the localhost, namely the user's computer. SWire expects to find both of them in a keystore which is called SWire keystore. The SWire keystore is a file named swire.keystore, written in the JKS format, which has to be located in the user's home directory. The latter depends on your operating system: for example, it may be /home/johndoe/ in Linux, thus the path to the SWire keystore may be /home/johndoe/swire.keystore. The SWire keystore can be generated by using the swire initsecurity command. The SWire keystore contains:
- a private key for secure communication with the SWire HTTPS server
- the SWire Certification Authority self-signed Certificate
- the localhost Certificate relating to the SWire HTTPS server.
The localhost Certificate is signed by the SWire Certification Authority, a fictional certification authority; this last is identified by a self-signed Certificate which is saved in the SWire keystore. In order to communicate with the SWire HTTPS server, a client must trust the localhost Certificate. For example, when connecting to the SWire HTTPS server, your browser may complain that this server is not reliable. This occurs because browsers refer to a list of trusted certification authorities and complain if the server Certificate has not been signed by a subject in this list. This list, which is also called store, can be mantained by your operating system or can be a list which is directly mantained by your browser. For example, Firefox uses a private list of trusted Certification Authorities.
The SWire Certification Authority self-signed Certificate should be added to the list of trusted Certification Authorities, used by your browser (or by other client you use for communicating with SWire). Accordingly, the localhost Certificate will be trusted because it has been signed by the SWire Certification Authority. The SWire Certification Authority Certificate can be exported to a file using the swire exportcert command. The use of the .cer file extension for the Certificate file is recommended for the exported Certificate.
The modality for trusting the SWire Certification Authority Certificate depends on your operating system; the following describes how to trust the SWire Certification Authority Certificate in Windows and Mac.
Trust the Certificate in Windows
To trust the SWire Certification Authority Certificate in Windows, follow the subsequent instructions:
1. Double-click on the Certificate (let suppose it was exported as "swire_ca.crt"):
2. Click on "Install Certificate...":
3. Place the Certificate in the "Trusted Root Certification Authorities" store:
Trust the Certificate in Mac
To trust the SWire Certification Authority Certificate in Mac, follow the subsequent instructions:
1. Double-click on the SWire Certification Authority Certificate file. The Keychain Access application will open and ask if you want to trust the Certificate:
2. Click on the button "Always Trust":
3. Leave Keychain Access open and search for the SWire Certification Authority Certificate. Right-click on the Certificate and select "Get Info". A dialog window will then appear with information relating to the Certificate:
4. Expand the "Trust" tab and select "Always trust" in the combobox labelled "Secure Sockets Layer (SSL)". Then close this dialog window to update the settings:
Testing the SWire HTTPS server
The following command can be executed in Stata to check if the SWire HTTPS local server is listening:
swire status
The SWire server can be tested by trying to open the SWire test page with a browser. If the SWire server is running in HTTP mode, the test page is
If the SWire server is running in HTTPS, the test page is:
The following is the screenshot of what Internet Explorer will display in the case you connect to the SWire test page but the SWire Certification Authoirty Certificate is not trusted:
You could click on "Continue to this website (not recommended)", but doing so the SWire server would be trusted only temporarily. The recommended way is to trust the SWire Certification Authority Certificate at the operating system level (see instruction for Windows and Mac which were given before).
The following is the screenshot of what Internet Explorer will display in the case you connect to the SWire test page and the SWire Certification Authoirty Certificate is trusted:
