Standard library · Security and cryptography

ssl

A familiar OpenSSL style interface for secure connections, on top of Salam's own TLS.

import ssl

On this page

Types
Constants and variables
Functions

This package gives the same OpenSSL style context and connection interface, but underneath it is Salam's own tls and it needs no outside library. For new code tls is simpler; this package is for code already written in this style. Set the hostname before Connect when certificates are verified.

The flow: make a context, hand the TCP connection to it with Wrap, for a client set the hostname and call Connect, then read and write.

Types

`Context`

struct Context

A TLS context, shared between connections.

Name	Type	Description
`handle`	`void*`	The pointer to the context state.

ssl-Client.salam

import ssl
import net.tcp

func main:
    ctx := ssl.NewClientContext()
    if not ssl.CtxOk(ctx):
        println ssl.LastErrorString()
        ret
    end
    _ := ssl.SetMinVersion(ctx, ssl.TLS1_3)
    _ := ssl.SetDefaultVerifyPaths(ctx)
    sock := tcp.Dial("example.com", 443)
    conn := ssl.Wrap(ctx, sock.fd)
    _ := ssl.SetHostname(conn, "example.com")
    if not ssl.ConnOk(conn) or not ssl.Connect(conn):
        println "the handshake failed:", ssl.LastErrorString()
        ret
    end
    println ssl.PeerVerified(conn), ssl.VerifyResult(conn) == ssl.CERT_OK
    n := ssl.Write(conn, "GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n")
    if n <= 0:
        println "error code:", ssl.ErrorCode(conn, n)
    end
    println ssl.Read(conn, 4096).len() > 0
    ssl.Shutdown(conn)
    ssl.Close(conn)
    ssl.CloseContext(ctx)
    tcp.Close(sock)
end

`Conn`

struct Conn

One TLS connection.

Name	Type	Description
`handle`	`void*`	The pointer to the connection state.

The example for this item is shown with the ones above: ssl-Client.salam

Constants and variables

`VERIFY_NONE`

const VERIFY_NONE: i32 = 0

Verification mode: no verification.

ssl-Server.salam

import ssl
import net.tcp

func main:
    ctx := ssl.NewServerContext("cert.pem", "key.pem")
    if not ssl.CtxOk(ctx):
        println ssl.LastErrorString()
        ret
    end
    ssl.SetVerify(ctx, ssl.VERIFY_NONE)
    _ := ssl.LoadVerifyLocationsFile(ctx, "clients-ca.pem")
    ssl.SetVerify(ctx, ssl.VERIFY_PEER)
    println ssl.FILETYPE_PEM, ssl.TLS1_2
    server := tcp.Bind(8443)
    until true:
        sock := tcp.Accept(server)
        conn := ssl.Wrap(ctx, sock.fd)
        if ssl.Accept(conn):
            request := ssl.Read(conn, 4096)
            _ := ssl.Write(conn, "HTTP/1.1 200 OK\r\nContent-Length: " + request.len() + "\r\n\r\n" + request)
        end
        ssl.Close(conn)
    end
end

`VERIFY_PEER`

const VERIFY_PEER: i32 = 1

Verification mode: verify the certificate of the other side.

The example for this item is shown with the ones above: ssl-Server.salam

`FILETYPE_PEM`

const FILETYPE_PEM: i32 = 1

The PEM file type.

The example for this item is shown with the ones above: ssl-Server.salam

`TLS1_2`

const TLS1_2: i32 = 771

The version number of TLS 1.2.

The example for this item is shown with the ones above: ssl-Server.salam

`TLS1_3`

const TLS1_3: i32 = 772

The version number of TLS 1.3.

The example for this item is shown with the ones above: ssl-Client.salam

`CERT_OK`

const CERT_OK: i64 = 0

Verification result: the certificate is valid.

The example for this item is shown with the ones above: ssl-Client.salam

Functions

`ErrorCode`

func ErrorCode(c: Conn, rc: int): int

The OpenSSL style error code for the result of one read or write.

The example for this item is shown with the ones above: ssl-Client.salam

`ConnErrorString`

func ConnErrorString(c: Conn): str

The error text of this connection; unlike LastErrorString it is not shared between threads.

The example for this item is shown with the ones above: ssl-Client.salam

`LastErrorString`

func LastErrorString(): str

The text of the last error, and clears it.

The example for this item is shown with the ones above: ssl-Client.salam

`Wrap`

func Wrap(ctx: Context, fd: i64): Conn

Makes a new SSL connection over an open socket.

The example for this item is shown with the ones above: ssl-Client.salam

`ConnOk`

func ConnOk(c: Conn): bool

The connection was created.

The example for this item is shown with the ones above: ssl-Client.salam

`Connect`

func Connect(c: Conn): bool

Does the client handshake.

The example for this item is shown with the ones above: ssl-Client.salam

`Accept`

func Accept(c: Conn): bool

Does the server handshake.

The example for this item is shown with the ones above: ssl-Server.salam

`Read`

func Read(c: Conn, max: int): str

Reads up to this many bytes.

The example for this item is shown with the ones above: ssl-Client.salam

`Write`

func Write(c: Conn, data: str): int

Sends data and returns the number of bytes, or a negative number on an error.

The example for this item is shown with the ones above: ssl-Client.salam

`Shutdown`

func Shutdown(c: Conn)

Sends the close alert.

The example for this item is shown with the ones above: ssl-Client.salam

`Close`

func Close(c: Conn)

Frees the connection.

The example for this item is shown with the ones above: ssl-Client.salam

`SetHostname`

func SetHostname(c: Conn, host: str): bool

Sets the hostname for SNI and for certificate verification.

The example for this item is shown with the ones above: ssl-Client.salam

`VerifyResult`

func VerifyResult(c: Conn): i64

The result of verifying the certificate of the other side.

The example for this item is shown with the ones above: ssl-Client.salam

`PeerVerified`

func PeerVerified(c: Conn): bool

The certificate of the other side was verified and accepted.

The example for this item is shown with the ones above: ssl-Client.salam

`NewClientContext`

func NewClientContext(): Context

A client context with TLS 1.2 as the minimum, certificate verification and the system roots.

The example for this item is shown with the ones above: ssl-Client.salam

`NewServerContext`

func NewServerContext(cert_file: str, key_file: str): Context

A server context with a certificate and key from files.

The example for this item is shown with the ones above: ssl-Server.salam

`CtxOk`

func CtxOk(ctx: Context): bool

The context was created.

The example for this item is shown with the ones above: ssl-Client.salam

`SetVerify`

func SetVerify(ctx: Context, mode: int)

The certificate verification mode.

The example for this item is shown with the ones above: ssl-Server.salam

`LoadVerifyLocationsFile`

func LoadVerifyLocationsFile(ctx: Context, path: str): bool

Reads the root certificates from a file.

The example for this item is shown with the ones above: ssl-Server.salam

`SetDefaultVerifyPaths`

func SetDefaultVerifyPaths(ctx: Context): bool

Loads the system roots.

The example for this item is shown with the ones above: ssl-Client.salam

`SetMinVersion`

func SetMinVersion(ctx: Context, version: i64): bool

The minimum TLS version.

The example for this item is shown with the ones above: ssl-Client.salam

`CloseContext`

func CloseContext(ctx: Context)

Frees the context.

The example for this item is shown with the ones above: ssl-Client.salam