Xb2.NET SSL - Frequently Asked Questions:

What is SSL and why do I need it?

Normal web traffic is sent unencrypted over the Internet. Anyone with access to the right tools can spy on all of that traffic. Obviously, this can lead to problems, especially where security and privacy is necessary, such as in credit card data and bank transactions. The Secure Socket Layer (SSL) is used to encrypt the data stream between the web server and the web client (the browser).

SSL makes use of what is known as asymmetric cryptography, commonly referred to as public key cryptography (PKI). With public key cryptography, two keys are created; one public and one private. Anything encrypted with either key can only be decrypted with its corresponding key. Thus if a message or data stream were encrypted with the server's private key, it can be decrypted only using its corresponding public key, ensuring that the data only could have come from the server.

If SSL utilizes public key cryptography to encrypt the data stream traveling over the Internet, why is a certificate necessary? The technical answer to that question is that a certificate is not really necessary; the data is secure and cannot easily be decrypted by a third party. However, certificates do serve a crucial role in the communication process. The certificate, signed by a trusted Certifying Authority (CA), ensures that the certificate holder is really who he claims to be. Without a trusted signed certificate, your data may be encrypted, however, the party you are communicating with may not be whom you think. Without certificates, impersonation attacks would be much more common.

What is PKI?

Public Key Infrastructure (PKI) is the entire system that supports the implementation and operation of a certificate-based public key cryptographic system.

What are RSA Private Keys, CSRs and Certificates?

The RSA private key file is a digital file that you can use to decrypt messages sent to you. It has a public component that you distribute (via your Certificate file) which allows people to encrypt those messages to you. A Certificate Signing Request (CSR) is a digital file containing your public key and your name. You send the CSR to a Certifying Authority (CA) to be converted into a real Certificate. A Certificate contains your RSA public key, your name, the name of the CA, and is digitally signed by your CA. Browsers that know the CA can verify the signature on that Certificate, thereby obtaining your RSA public key. This enables them to send messages that only you can decrypt.

What does a Digital Certificate contain?

Digital Certificates contain the owner's public key, the owner's name, an expiration date, the name of the Certifying Authority that issued the Digital Certificate, a serial number, and perhaps some other information.

How can I create a dummy SSL server Certificate for testing purposes?

A Certificate does not have to be signed by a public CA. You can use your private key to sign the Certificate which contains your public key. This is commonly referred to as a "self-signed certificate". Client browsers will display a warning dialog indicating that the signing certificate authority is unknown and not trusted when trying to connect to an HTTPS server that uses a self-signed certificate. Users can eliminate this warning dialog by manually installing the certificate into their browsers.

The following OpenSSL command will create a self-signed certificate named MYCERT.PEM. This command uses a configuration file, XB2NET.CNF that is included with the Xb2.NET OpenSSL distribution package. The generated certificate expires after 90 days and is not encrypted:

openssl req -new -x509 -days 90 -nodes -config xb2net.cnf -out mycert.pem -keyout mycert.pem

How can I create a real SSL certificate signed by public CA (Certifying Authority)?

Here is a step-by-step description:

  1. Run the following OpenSSL command to create a CSR (certificate signing request) and private key. This command uses a configuration file, XB2NET.CNF which is included with the Xb2.NET OpenSSL distribution package:

    openssl req -new -nodes -keyout mykey.pem -out mycsr.pem -config xb2net.cnf -newkey rsa:2048

    The above command will create two files: MYKEY.PEM (your private key) and MYCSR.PEM (the Certificate Signing Request).

    During the generation of the CSR, you will be prompted for several pieces of information. These are the X.509 attributes of the certificate. One of the prompts will be for "Common Name (server domain/host name)". It is important that this field be filled in with the fully qualified domain name of the server to be protected by SSL. If the website to be protected will be https://www.server.com, then enter www.server.com at this prompt.

    A sample CSR generation session is shown below, with sample responses highlighted:
    D:\OpenSSL>openssl req -new -nodes -keyout mykey.pem -out mycsr.pem -config xb2net.cnf -newkey rsa:2048
    Loading 'screen' into random state - done
    Generating a 4096 bit RSA private key
    ......................................++++++
    ............................++++++
    writing new private key to 'mykey.pem'
    -----
    You are about to be asked to enter information that will be incorporated
    into your certificate request.
    What you are about to enter is what is called a Distinguished Name or a DN.
    There are quite a few fields but you can leave some blank
    For some fields there will be a default value,
    If you enter '.', the field will be left blank.
    -----
    Country Name (2 letter code) [AU]:CA
    State or Province Name (full name) [Some-State]:ON
    Locality Name (eg, city) []:Toronto
    Organization Name (eg, company) [Internet Widgits Pty Ltd]:Cool Software Inc.
    Organizational Unit Name (eg, section) []:
    Common Name (server domain/host name) []:coolsoftware.com
    Email Address []:admin@coolsoftware.com
    
    Please enter the following 'extra' attributes
    to be sent with your certificate request
    A challenge password []:
    An optional company name []:
    
    D:\OpenSSL>
  2. Backup the MYKEY.PEM file and keep it private. Do not disclose this file to anyone since it contains your private key, which can be used to decrypt messages intended for you. In particular, make sure to backup the private key because there is no way to recover it in case it is lost.

  3. Send MYCSR.PEM to a Certifying Authority (CA) for signing. The process typically involves posting the CSR into a web form, paying for the signing and then waiting for the signed certificate to be emailed to you. This process can take anywhere from several minutes to a few days. Here is a list of some commercial CAs:


  4. Receive certificate from CA by email (certificate is digitally signed by your CA and contains your public key, your name, and the name of the CA). The certificate may be received as either a separate file attachment or as base64-encoded text within the email body. In the later case, you can copy and paste the certificate text (including the lines that say BEGIN CERTIFICATE and END CERTIFICATE) into a text file for use within your application. You can see the details of the received Certificate via the following OpenSSL command (assuming MYCERT.PEM is the name of the certificate file):

    openssl x509 -noout -text -in mycert.pem

  5. In order to simplify things, you can combine your private key (created in step 1) and the certificate (received in step 4) into one file. Create a new text file, eg. MYCERT.PEM as follows:
    1. Copy and paste all text from MYKEY.PEM (created in step 1)
    2. Append certificate text received from Certifying Authority (item 4 above)

    You should have a text file that looks something like this:
    -----BEGIN RSA PRIVATE KEY-----
    MIICXAIBAAKBgQCquFagDY6vXyrqGEmg5jNMy8cgWm9HeaKUoz5JPqGRV9KoWMDe
    0MFG1iBobMzsuWv+FdWEv8wneVhSJGTrLJJ5XY5vZVxK9Q3DUl9Sl7/VAund2VI1
    3udB67ta9+H7+j42d8zW8SejSkCLsilnHLsBMmDt2tfj9cPc2Ge+GKIXRwIDAQAB
    AoGAVSB8GW0JNAtpU7dup2uCMw39qfVOPb66QhGwUkeHuvim00kGS1Seu5q0KD3w
    ZS4EWns6r+oPe7N3ReZd6CKemlLUgRKDdVGCYCOT8vp03p/KVnv6yQ7GbK5hO3Hx
    /muP5VIzg85ZFdvscsHlrAWz6tRLhcoygjJa5GF998t47tkCQQDiarzfi1DHPlhU
    cnPUz2OA/WU+G+s3ztkk2mlF/x877QRfAdxT5k/KRnWi7xS+fCyxgI5mteMxbNTo
    k/KHqwUFAkEAwQaigqW2bsUylsz9e30RH5YsDVkcyhXGCBx5b+odDevp6Gepiyj2
    JQw/Uzq+0ugRHJfw69ajk9EdWfLinBtc2wJAMbNgdmmsd7AVz6O4DXTg0MXO3Y1f
    WsbLH63aAgV4o7zpgrlz1e7ugOZqmDOHCDFV1jj0CVPP5V+QdOVVDbbayQJADD5c
    fob+XGZbwB7+kR+sv2EqKCqX3eWlqwwLU+L4ttJZAunYYkBV5KGzPpdCVWRs+XBV
    0s/Jjm28O+FhKF+/8wJBALOvzUkUxhOVDtZdStwhKaLaRsDtCiKvI6zAAeF1g3rN
    /W69ZgvRaUsta9I19jDl1kiidDScnvypsg7cmh2UMeE=
    -----END RSA PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIIDOTCCAqKgAwIBAgIBADANBgkqhkiG9w0BAQQFADB3MQswCQYDVQQGEwJDQTEQ
    MA4GA1UECBMHT250YXJpbzEQMA4GA1UEBxMHVG9yb250bzEQMA4GA1UEChMHWGIy
    Lk5FVDESMBAGA1UEAxMJbG9jYWxob3N0MR4wHAYJKoZIhvcNAQkBFg9zdXBwb3J0
    QHhiMi5uZXQwHhcNMDUwMTA3MTcwMTQzWhcNMTUwMTA1MTcwMTQzWjB3MQswCQYD
    VQQGEwJDQTEQMA4GA1UECBMHT250YXJpbzEQMA4GA1UEBxMHVG9yb250bzEQMA4G
    A1UEChMHWGIyLk5FVDESMBAGA1UEAxMJbG9jYWxob3N0MR4wHAYJKoZIhvcNAQkB
    Fg9zdXBwb3J0QHhiMi5uZXQwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAKq4
    VqANjq9fKuoYSaDmM0zLxyBab0d5opSjPkk+oZFX0qhYwN7QwUbWIGhszOy5a/4V
    1YS/zCd5WFIkZOssknldjm9lXEr1DcNSX1KXv9UC6d3ZUjXe50Hru1r34fv6PjZ3
    zNbxJ6NKQIuyKWccuwEyYO3a1+P1w9zYZ74YohdHAgMBAAGjgdQwgdEwHQYDVR0O
    BBYEFEhcvVIyTaJpZ5x/Vz1VvUuv5rkcMIGhBgNVHSMEgZkwgZaAFEhcvVIyTaJp
    Z5x/Vz1VvUuv5rkcoXukeTB3MQswCQYDVQQGEwJDQTEQMA4GA1UECBMHT250YXJp
    bzEQMA4GA1UEBxMHVG9yb250bzEQMA4GA1UEChMHWGIyLk5FVDESMBAGA1UEAxMJ
    bG9jYWxob3N0MR4wHAYJKoZIhvcNAQkBFg9zdXBwb3J0QHhiMi5uZXSCAQAwDAYD
    VR0TBAUwAwEB/zANBgkqhkiG9w0BAQQFAAOBgQBzYzdwpbuMH6hIWtOFuVLd3R9M
    bw0h4xAEIhLmR82g8UgR5c6fxGIz/igod1XkNCvSaB1BXOA4aSGirYEqjuty1/HS
    jaoG9Yd2AsccTBxrLVmy7I2LRdoxHoc1P9lmw/KUVDUlqgjOpF1imtBf6y50DpoY
    39Fz7R54S85jzRGdOw==
    -----END CERTIFICATE-----

How do I use the certificate in my Xb2.NET web server?

Assuming that your certificate and private key were created as described above, you should have a file called MYCERT.PEM. You can reference this file as follows within your Xb2.NET application:

    // define SSL context
    oSSL := xbSSLContext():new( TLS_server_method )
    // if the private key is password protected, you can supply the password using this method:
    // oSSL:SetDefaultPassword("xYq9h750eL3")
    oSSL:UseCertificateFile("MYCERT.PEM")
    oSSL:UsePrivateKeyFile("MYCERT.PEM")
    
    // check private key
    if ! oSSL:CheckPrivateKey()
       MsgBox("Private key does not match certificate!" + chr(10) + xbSSLGetLastError())
    endif
    
    // attach SSL context to HTTP server instance
    oHTTPS := xbHTTPServer():new(INADDR_ANY, 443, oSSL)
    oHTTPS:start()

Here are some additional examples of using the OpenSSL command line utility:

(1) Display OpenSSL version information:
openssl version

(2) Remove the password phrase on an RSA private key:
openssl rsa -in key.pem -out keyout.pem

(3) Encrypt a private key using triple DES:
openssl rsa -in key.pem -des3 -out keyout.pem

(4) Convert a private key from PEM to DER format:
openssl rsa -in key.pem -outform DER -out keyout.der

(5) Print out the components of a private key:
openssl rsa -in key.pem -text -noout

(6) Extract the public key from a private key:
openssl rsa -in key.pem -pubout -out pubkey.pem

(7) Extract the public key from an x509 certificate:
openssl x509 -in cert.pem -pubkey -out pubkey.pem

(8) Convert a certificate from PEM to DER format:
openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER

(9) Verify a certificate:
openssl verify -purpose any cert.pem

(10) Encrypt a file (myfile) using AES-256-CBC cipher:
openssl aes-256-cbc -in myfile -out myfile.enc -pass pass:MyPassword

(11) Decrypt a previously encrypted file (myfile.enc) using AES-256-CBC cipher:
openssl aes-256-cbc -d -in myfile.enc -out myfile -pass pass:MyPassword

(12) Generate sha256 hash of a file (add -binary param to generate binary output):
openssl dgst -sha256 myfile > hash

(13) Digitally sign a document (myfile) using a private key (key.pem):
openssl dgst -sha256 -sign key.pem -out myfile.sig myfile

(14) Verify a document (myfile) given a signature file (myfile.sig) and public key (pubkey.pem).
Note: The public key can be extracted from a private key (see #6 above) or a x509 certificate (see #7 above).
openssl dgst -sha256 -verify pubkey.pem -signature myfile.sig myfile



Xb2.NET homepage