Openssl v1.0.0 documentation

Documentation generated by XL CLAIRE v3.3.37 at Fri, 17 Nov 2006

• Author : Sylvain BENILAN

Category index

1. Algorithms
2. Key pair
3. Message digest, signing, verifying
4. X509
5. PKCS#7
6. PKCS#8
7. PKCS#12
8. SSL

Global Variable index

• CYPHERS :: {"des-cbc", "des-ecb", "des-cfb", "des-ofb", "des-ede-cbc", "des-ede", "des-ede-ofb", "des-ede-cfb", "des-ede3-cbc", "des-ede3", "des-ede3-ofb", "des-ede3-cfb", "desx-cbc", "rc4", "rc4-40", "idea-cbc", "idea-ecb", "idea-cfb", "idea-ofb", "rc2-cbc", "rc2-ecb", "rc2-cfb", "rc2-ofb", "rc2-40-cbc", "rc2-64-cbc", "bf-cbc", "bf-ecb", "bf-cfb", "bf-ofb", "cast5-cbc", "cast5-ecb", "cast5-cfb", "cast5-ofb", "rc5-32-12-16-cbc", "rc5-32-12-16-ecb", "rc5-32-12-16-cfb", "rc5-32-12-16-ofb"}
• DIGEST_ALGORYTHMS :: {"null", "md2", "md5", "sha", "sha1", "dss", "dss1", "mdc2", "ripemd160"}
• VERIFY_FLAGS :: {"ignore_critical", "issuer_checks", "crl_check", "crl_check_all"}
• VERIFY_PURPOSE :: {"sslclient", "sslserver", "nssslserver", "smimesign", "smimeencrypt", "ocsphelper", "any"}

Method index

• add_extension (self:X509, nid:integer, value:string) -> void
• add_extension (self:X509, txt:string, value:string) => void
• add_issuer_entry (self:X509, field:string, val:string) -> void
• add_subject_entry (self:X509, field:string, val:string) -> void
• append_X509_pem (self:X509, pem_file:string) -> void
• d2i_PKCS12 (self:string, pass:string) -> tuple(X509, key)
• d2i_PKCS8 (self:string, pass:string) -> key
• d2i_private (self:string) -> key
• d2i_public (self:string) -> key
• d2i_X509 (self:string) -> X509
• decrypt (p7:PKCS7, recipient:X509, pkey:key) -> blob
• decrypt&verify (p7:PKCS7, recipient:X509, pkey:key, trusted:list[X509], untrusted:list[X509], out:port) -> boolean
• digest (algo:DIGEST_ALGORYTHMS, msg:string) -> string
• digest_context! (algo:DIGEST_ALGORYTHMS) -> digest_context
• digest_filter! (self:port, algo:DIGEST_ALGORYTHMS) -> digest_filter
• digest_final (self:digest_context) -> string
• digest_init (self:digest_context) -> void
• digest_update (self:digest_context, msg:string) -> void
• dsa! (nbits:1 .. 1024) -> key
• encrypt (recipients:list[X509], indata:port) -> PKCS7
• get_issuer (self:X509) -> string
• get_issuer_entry (self:X509, field:string) -> string
• get_issuer_entry_count (self:X509) -> integer
• get_pubkey (self:X509) -> key
• get_recipients (self:PKCS7, possibles:list[X509]) -> list[X509]
• get_serial (self:X509) -> integer
• get_signers (self:PKCS7) -> list[X509]
• get_subject (self:X509) -> string
• get_subject_entry (self:X509, field:string) -> string
• get_subject_entry_count (self:X509) -> integer
• get_version (self:X509) -> integer
• i2d (self:X509) -> string
• i2d (self:key, pass:string) -> string
• i2d (self:key, algo:CYPHERS, pass:string) -> string
• i2d (self:X509, pkey:key, name:string, pass:string) -> string
• i2d_private (self:key) -> string
• i2d_public (self:key) -> string
• key_size (self:key) -> integer
• key_type (self:key) -> string
• load_X509_pem (pem_file:string) -> list[X509]
• pem2private (pem:string) -> key
• pem2private (pem:string, pass:string) -> key
• pem2public (pem:string) -> key
• pem2X509 (pem:string) -> X509
• private2pem (self:key) -> string
• private2pem (self:key, algo:CYPHERS, pass:string) -> string
• public2pem (self:key) -> string
• rsa! (nbits:integer) -> key
• save_X509_pem (self:X509, pem_file:string) -> void
• sclient! (addr:string, p:integer) -> ssl_socket
• set_authority_info_access (self:X509, authority_info_access:string) -> void
• set_authority_key_identifier (self:X509, authority_key_identifier:string) -> void
• set_basic_constraints (self:X509, basic_constraints:string) -> void
• set_crl_distribution_points (self:X509, clr_distribution_points:string) -> void
• set_issuer (self:X509, issuer:X509) -> void
• set_issuer_alt_name (self:X509, issuer_alt_name:string) -> void
• set_key_usage (self:X509, key_usage:string) -> void
• set_not_after (self:X509, days:integer) -> void
• set_not_before (self:X509, days:integer) -> void
• set_serial (self:X509, serial:integer) -> void
• set_subject_alt_name (self:X509, subject_alt_name:string) -> void
• set_subject_key_identifier (self:X509, subject_key_identifier:string) -> void
• set_version (self:X509, ver:{0, 1, 2}) -> void
• sign (self:X509, k:key) => void
• sign (self:X509, k:key, algo:DIGEST_ALGORYTHMS) -> void
• sign (self:DIGEST_ALGORYTHMS, msg:string, k:key) -> string
• sign (signer:X509, pkey:key, chain:list[X509], data:port) -> PKCS7
• sign&encrypt (signer:X509, pkey:key, chain:list[X509], recipients:list[X509], data:port) -> PKCS7
• sign_filter! (self:port, algo:DIGEST_ALGORYTHMS) -> sign_filter
• sign_final (self:digest_context, k:key) -> string
• sign_final (self:sign_filter, k:key) -> string
• sign_init (self:digest_context) -> void
• sign_update (self:digest_context, msg:string) -> void
• verify (self:X509, k:key) -> boolean
• verify (self:X509, trusted:list[X509], untrusted:list[X509]) => boolean
• verify (self:DIGEST_ALGORYTHMS, msg:string, signature:string, k:key) -> boolean
• verify (self:PKCS7, trusted:list[X509], untrusted:list[X509], p:port) -> boolean
• verify (self:X509, trusted:list[X509], untrusted:list[X509], flags:subtype[VERIFY_FLAGS], purpose:VERIFY_PURPOSE) -> boolean
• verify_filter! (self:port, algo:DIGEST_ALGORYTHMS) -> verify_filter
• verify_final (self:verify_filter, digest:string, k:key) -> boolean
• verify_final (self:digest_context, digest:string, k:key) -> boolean
• verify_init (self:digest_context) -> void
• verify_update (self:digest_context, msg:string) -> void
• X509! (k:key) -> X509
• X5092pem (self:X509) -> string

Openssl categories

Algorithms

• CYPHERS :: {"des-cbc", "des-ecb", "des-cfb", "des-ofb", "des-ede-cbc", "des-ede", "des-ede-ofb", "des-ede-cfb", "des-ede3-cbc", "des-ede3", "des-ede3-ofb", "des-ede3-cfb", "desx-cbc", "rc4", "rc4-40", "idea-cbc", "idea-ecb", "idea-cfb", "idea-ofb", "rc2-cbc", "rc2-ecb", "rc2-cfb", "rc2-ofb", "rc2-40-cbc", "rc2-64-cbc", "bf-cbc", "bf-ecb", "bf-cfb", "bf-ofb", "cast5-cbc", "cast5-ecb", "cast5-cfb", "cast5-ofb", "rc5-32-12-16-cbc", "rc5-32-12-16-ecb", "rc5-32-12-16-cfb", "rc5-32-12-16-ofb"}
• DIGEST_ALGORYTHMS :: {"null", "md2", "md5", "sha", "sha1", "dss", "dss1", "mdc2", "ripemd160"}

Key pair

• d2i_private (self:string) -> key
• d2i_public (self:string) -> key
• dsa! (nbits:1 .. 1024) -> key
• i2d_private (self:key) -> string
• i2d_public (self:key) -> string
• key_size (self:key) -> integer
• key_type (self:key) -> string
• pem2private (pem:string) -> key
• pem2private (pem:string, pass:string) -> key
• pem2public (pem:string) -> key
• private2pem (self:key) -> string
• private2pem (self:key, algo:CYPHERS, pass:string) -> string
• public2pem (self:key) -> string
• rsa! (nbits:integer) -> key

This section describes methods that are used to create key pairs. A key pair is made of a public key known to everyone and a private or secret key known only to the recipient of a message. When someone wants to send a secure message to someone else, he uses recipient's public key to encrypt the message. The recipient then uses its private key to decrypt the message.

An important element to the public key system is that the public and private keys are related in such a way that only the public key can be used to encrypt messages and only the corresponding private key can be used to decrypt them. Moreover, it is virtually impossible to deduce the private key if you know the public key.

The Openssl CLAIRE module supports two kinds of key pairs :

• RSA : Rivest-Shamir-Adleman, the name of its inventors
• DSA : Digital Signature Standard

Message digest, signing, verifying

• digest (algo:DIGEST_ALGORYTHMS, msg:string) -> string
• digest_context! (algo:DIGEST_ALGORYTHMS) -> digest_context
• digest_filter! (self:port, algo:DIGEST_ALGORYTHMS) -> digest_filter
• digest_final (self:digest_context) -> string
• digest_init (self:digest_context) -> void
• digest_update (self:digest_context, msg:string) -> void
• sign (self:DIGEST_ALGORYTHMS, msg:string, k:key) -> string
• sign_filter! (self:port, algo:DIGEST_ALGORYTHMS) -> sign_filter
• sign_final (self:digest_context, k:key) -> string
• sign_final (self:sign_filter, k:key) -> string
• sign_init (self:digest_context) -> void
• sign_update (self:digest_context, msg:string) -> void
• verify (self:DIGEST_ALGORYTHMS, msg:string, signature:string, k:key) -> boolean
• verify_filter! (self:port, algo:DIGEST_ALGORYTHMS) -> verify_filter
• verify_final (self:digest_context, digest:string, k:key) -> boolean
• verify_final (self:verify_filter, digest:string, k:key) -> boolean
• verify_init (self:digest_context) -> void
• verify_update (self:digest_context, msg:string) -> void

A message digest is a representation of a text in the form of a single string of digits, created using a formula called a one-way hash function. Encrypting a message digest with a private key creates a digital signature, which is an electronic means of authentication.

X509

• add_extension (self:X509, txt:string, value:string) => void
• add_extension (self:X509, nid:integer, value:string) -> void
• add_issuer_entry (self:X509, field:string, val:string) -> void
• add_subject_entry (self:X509, field:string, val:string) -> void
• append_X509_pem (self:X509, pem_file:string) -> void
• d2i_X509 (self:string) -> X509
• get_issuer (self:X509) -> string
• get_issuer_entry (self:X509, field:string) -> string
• get_issuer_entry_count (self:X509) -> integer
• get_pubkey (self:X509) -> key
• get_serial (self:X509) -> integer
• get_subject (self:X509) -> string
• get_subject_entry (self:X509, field:string) -> string
• get_subject_entry_count (self:X509) -> integer
• get_version (self:X509) -> integer
• i2d (self:X509) -> string
• load_X509_pem (pem_file:string) -> list[X509]
• pem2X509 (pem:string) -> X509
• save_X509_pem (self:X509, pem_file:string) -> void
• set_authority_info_access (self:X509, authority_info_access:string) -> void
• set_authority_key_identifier (self:X509, authority_key_identifier:string) -> void
• set_basic_constraints (self:X509, basic_constraints:string) -> void
• set_crl_distribution_points (self:X509, clr_distribution_points:string) -> void
• set_issuer (self:X509, issuer:X509) -> void
• set_issuer_alt_name (self:X509, issuer_alt_name:string) -> void
• set_key_usage (self:X509, key_usage:string) -> void
• set_not_after (self:X509, days:integer) -> void
• set_not_before (self:X509, days:integer) -> void
• set_serial (self:X509, serial:integer) -> void
• set_subject_alt_name (self:X509, subject_alt_name:string) -> void
• set_subject_key_identifier (self:X509, subject_key_identifier:string) -> void
• set_version (self:X509, ver:{0, 1, 2}) -> void
• sign (self:X509, k:key) => void
• sign (self:X509, k:key, algo:DIGEST_ALGORYTHMS) -> void
• verify (self:X509, k:key) -> boolean
• verify (self:X509, trusted:list[X509], untrusted:list[X509]) => boolean
• verify (self:X509, trusted:list[X509], untrusted:list[X509], flags:subtype[VERIFY_FLAGS], purpose:VERIFY_PURPOSE) -> boolean
• VERIFY_FLAGS :: {"ignore_critical", "issuer_checks", "crl_check", "crl_check_all"}
• VERIFY_PURPOSE :: {"sslclient", "sslserver", "nssslserver", "smimesign", "smimeencrypt", "ocsphelper", "any"}
• X509! (k:key) -> X509
• X5092pem (self:X509) -> string

X509 certificates use Public Key Infrastructure (PKI) to support certificate creation and verification. In PKI, key pairs are generated where one key is kept private (private key) and one key is given away freely (public key). Data encrypted with a private key can only be decrypted with the matching public key and data encrypted with the public key can only be decrypted with the matching private key.

In this section we'll create a sample Certification Authority by hand. As a first step we need a key pair and a CA certificate :

ca_key :: Openssl/rsa!(512)  ca :: Openssl/X509!(ca_key)

Then we'll add to the CA certificate a subject entry :

(Openssl/add_subject_entry(ca, "CN","CARoot"))  (Openssl/add_subject_entry(ca, "O","claire-language"))  (Openssl/add_subject_entry(ca, "C","FR"))

Our CA certificate is a root certificate (self signed) :

(Openssl/set_issuer(ca,ca)) // self issued

We now update its serial number and validity period :

(Openssl/set_serial(ca,0))  (Openssl/set_not_before(ca, -1))  (Openssl/set_not_after(ca, 3000))

Then we set some X509 v3 extensions :

(Openssl/set_basic_constraints(ca, "critical,CA:true,pathlen:1"))  (Openssl/set_subject_key_identifier(ca, "hash"))  (Openssl/set_authority_key_identifier(ca, "keyid:always,issuer:always"))  (Openssl/set_key_usage(ca, "critical,keyCertSign,cRLSign"))

And as a last step we (self) sign the certificate and save it in the PEM format to the file ca.pem :

(Openssl/sign(ca, ca_key))  (Openssl/save_X509_pem(ca, "ca.pem"))

Since we now have a CA certificate we can create a user certificate following the same steps as above. Note that the user certificate is issued and signed with the above certificate :

cert_key :: Openssl/rsa!(512)  cert :: Openssl/X509!(cert_key)  (Openssl/add_subject_entry(cert, "CN","some_user"))  (Openssl/add_subject_entry(cert, "O","claire-language"))  (Openssl/add_subject_entry(cert, "C","FR"))  (Openssl/set_issuer(cert, ca)) // issued by our CA  (Openssl/set_serial(cert, 1))  (Openssl/set_not_before(cert, -1))  (Openssl/set_not_after(cert, 30)) // 30 days validity period  (Openssl/set_key_usage(cert, "critical,digitalSignature,nonRepudiation,keyEncipherment"))  (Openssl/set_subject_key_identifier(cert, "hash"))  (Openssl/set_authority_key_identifier(cert, "keyid:always,issuer:always"))  (Openssl/sign(cert, ca_key))  (Openssl/save_X509_pem(cert, "cert.pem"))

Last we may verify that our user certificate is valid :

cert :: Openssl/load_X509_pem("cert.pem")[1]  (if verify(cert, Openssl/load_X509_pem("ca.pem"), nil)          printf("~S is valid\n", cert)  else printf("~S is not valid (~A)\n", cert, cert.Openssl/verify_message))

PKCS#7

• decrypt (p7:PKCS7, recipient:X509, pkey:key) -> blob
• decrypt&verify (p7:PKCS7, recipient:X509, pkey:key, trusted:list[X509], untrusted:list[X509], out:port) -> boolean
• encrypt (recipients:list[X509], indata:port) -> PKCS7
• get_recipients (self:PKCS7, possibles:list[X509]) -> list[X509]
• get_signers (self:PKCS7) -> list[X509]
• sign (signer:X509, pkey:key, chain:list[X509], data:port) -> PKCS7
• sign&encrypt (signer:X509, pkey:key, chain:list[X509], recipients:list[X509], data:port) -> PKCS7
• verify (self:PKCS7, trusted:list[X509], untrusted:list[X509], p:port) -> boolean

In this section we'll create a signed and encryted PKCS#7 and verify it. For that purpose we need a CA trusted certificate, a singer certificate and a least one recipient certificate. The creation of certificate is described in the X509 section and we'll assume that it exists a file ca.pem that contain a single PEM CA certificate. We also assume that we have two files containing DER encoded PKCS#12 (cert1.p12, cert2.p12) of user certificates issued by our CA :

cas :: Openssl/load_X509_pem("ca.pem") // the list of CA  load_p12(filename:string, pass:string) : tuple(Openssl/X509, Openssl/key) ->      let f := fopen(filename,"r"),          p12 := fread(f),      in (fclose(f),          Openssl/d2i_PKCS12(p12, pass))  // load (cert, private key) pairs  signer :: load_p12("cert1.p12", "cert1_password")  recipient :: load_p12("cert2.p12", "cert2_password")

We should verify certificates validity :

(assert(Openssl/verify(signer[1], cas, nil) &          Openssl/verify(recipient[1], cas, nil)))

We now create a message signed by our signer and encrytped for our recipient :

p7 :: Openssl/sign&encrypt(signer[1], signer[2], nil,              list(recipient[1]),              blob!("some message"))

This PKCS#7 can now be decrypted by our recipient :

b :: blob!()  (if Openssl/decrypt&verify(p7, recipient[1], recipient[2], cas, nil, b)      printf("PKCS#7 decrypted and verifyed\n")  else error("Couldn't verify PKCS#7 : ~A", p7.Openssl/verify_message))  (assert(fread(b) = "some message"))

i2d(self) generates a DER encoded version of the given PKCS#7.

d2i_PKCS7(self) returns a DER decoded PKCS#7.

PKCS72pem(self) generates a PEM encoded version of the given PKCS#7.

pem2PKCS7(pem) returns a PEM decoded PKCS#7.

PKCS#8

• d2i_PKCS8 (self:string, pass:string) -> key
• i2d (self:key, pass:string) -> string
• i2d (self:key, algo:CYPHERS, pass:string) -> string

This standard specifies a syntax for encrypted private keys.

PKCS#12

• d2i_PKCS12 (self:string, pass:string) -> tuple(X509, key)
• i2d (self:X509, pkey:key, name:string, pass:string) -> string

This standard specifies a portable format for storing or transporting a user's private key and certificate.

SSL

• sclient! (addr:string, p:integer) -> ssl_socket

Openssl global variables

Openssl/CYPHERS :: {"des-cbc", "des-ecb", "des-cfb", "des-ofb", "des-ede-cbc", "des-ede", "des-ede-ofb", "des-ede-cfb", "des-ede3-cbc", "des-ede3", "des-ede3-ofb", "des-ede3-cfb", "desx-cbc", "rc4", "rc4-40", "idea-cbc", "idea-ecb", "idea-cfb", "idea-ofb", "rc2-cbc", "rc2-ecb", "rc2-cfb", "rc2-ofb", "rc2-40-cbc", "rc2-64-cbc", "bf-cbc", "bf-ecb", "bf-cfb", "bf-ofb", "cast5-cbc", "cast5-ecb", "cast5-cfb", "cast5-ofb", "rc5-32-12-16-cbc", "rc5-32-12-16-ecb", "rc5-32-12-16-cfb", "rc5-32-12-16-ofb"}

CYPHERS contains the names of valid algorithms used for encryption.

Openssl/DIGEST_ALGORYTHMS :: {"null", "md2", "md5", "sha", "sha1", "dss", "dss1", "mdc2", "ripemd160"}

DIGEST_ALGORYTHMS contains the names of valid algorithms used for digest and digital signature calculations.

Openssl/VERIFY_FLAGS :: {"ignore_critical", "issuer_checks", "crl_check", "crl_check_all"}

Flags supported for the X509 certficate verification.

Openssl/VERIFY_PURPOSE :: {"sslclient", "sslserver", "nssslserver", "smimesign", "smimeencrypt", "ocsphelper", "any"}

Purposes supported for the X509 certficate verification.

Openssl methods

Openssl/add_extension(self:X509, txt:string, value:string) => void

add_extension(self, txt, value) is a general tools to add a v3 extension to an X509 by a NID name.

Openssl/add_extension(self:X509, nid:integer, value:string) -> void

add_extension(self, nid, value) is a general tools to add a v3 extension to an X509 by a NID value.

Openssl/add_issuer_entry(self:X509, field:string, val:string) -> void

add_issuer_entry(self, field, val) adds an entry in the issuer distinguish name (DN) of the given certificate, for instance :

• "CN" common name
• "C" country name
• "L" locality name
• "ST" state or province name
• "O" organization name
• "OU" organizational unit name
• "emailAddress" email address
• ...

Openssl/add_subject_entry(self:X509, field:string, val:string) -> void

add_issuer_entry(self, field, val) adds an entry in the subject distinguish name (DN) of the given certificate, for instance :

• "CN" common name
• "C" country name
• "L" locality name
• "ST" state or province name
• "O" organization name
• "OU" organizational unit name
• "emailAddress" email address
• ...

Openssl/append_X509_pem(self:X509, pem_file:string) -> void

append_X509_pem(self, pem_file) appends a PEM encoded certificate to the given file.

Openssl/d2i_PKCS12(self:string, pass:string) -> tuple(X509, key)

d2i_PKCS12(self, pass) decode a PKCS#12 that have been encrypted with a password. The returnes value is a tuple containing an X509 public certificate and its associated private key.

Openssl/d2i_PKCS8(self:string, pass:string) -> key

d2i_PKCS8(self, pass) decoded an encrypted DER encoded PKCS#8 with the given password.

Openssl/d2i_private(self:string) -> key

d2i_private(self) decodes a DER encoded private key.

Openssl/d2i_public(self:string) -> key

d2i_public(self) decodes a DER encoded public key.

Openssl/d2i_X509(self:string) -> X509

d2i_X509(self) decodes a DER encoded certificate.

Openssl/decrypt(p7:PKCS7, recipient:X509, pkey:key) -> blob

decrypt(p7, recipient, pkey) extract the encrypted content of the given PKCS#7 for the specified recipient public cetificate and associated private key pkey.

Openssl/decrypt&verify(p7:PKCS7, recipient:X509, pkey:key, trusted:list[X509], untrusted:list[X509], out:port) -> boolean

decrypt&verify(p7, recipient, pkey, trusted, untrusted, out) fills the port out with the content of a signed and encrypted PKCS#7. This operation is performed for the given recipient that should be part of the recipients of the PKCS#7. In order to verify the the signer of the supplied PKCS#7 one should specify certificates of trusted CAs, and optionaly a list of untrusted certificates. The returned value is true is the verification process succeded, otherwise false is returned and p7.verify_message can be used to get the information why the verification failed.

Openssl/digest(algo:DIGEST_ALGORYTHMS, msg:string) -> string

Calculates a digest value for a given message msg. It is equivalent to :

let ctx := Openssl/digest_context!(algo)  in (Openssl/digest_init(ctx),      Openssl/digest_update(ctx, msg),      Openssl/digest_final(ctx))

Openssl/digest_context!(algo:DIGEST_ALGORYTHMS) -> digest_context

digest_context!(algo) returns a digest context for the given digest algorithm.

Openssl/digest_filter!(self:port, algo:DIGEST_ALGORYTHMS) -> digest_filter

digest_filter!(self, algo) creates filter that internaly manage a digest context. Everything written through this filter is used to update the internal state of the digest. Once the returned filter is closed one can find the digest value in the digest field of the filter :

let b := blob!(),      digester := Openssl/digest_filter!(b, "sha")  in (fwrite(digester, "some messages"),          fclose(digester),          let digest := digester.Openssl/digest          in (...))

Openssl/digest_final(self:digest_context) -> string

digest_final(self) finilize the internal state of the digest context and return the digest value.

Openssl/digest_init(self:digest_context) -> void

digest_init(self) initialise a digest context.

Openssl/digest_update(self:digest_context, msg:string) -> void

digest_update(self, msg) update the internal state of the digest context with the addition of the given message msg.

Openssl/dsa!(nbits:1 .. 1024) -> key

rsa!(nbits) generates an DSA key pair (private and public keys) of the given size nbits. nbits should be a 2 exponent.

Openssl/encrypt(recipients:list[X509], indata:port) -> PKCS7

encrypt(recipients, indata) creates a PKCS#7 with an encrypted content for the given recipients public certificates. The content is made of what can be read on indata.

Openssl/get_issuer(self:X509) -> string

get_issuer(self) return the an issuer's DN in the form "/CN=val/field=val...".

Openssl/get_issuer_entry(self:X509, field:string) -> string

get_issuer_entry(self, field) returns the issuer's DN entry value for the given field name.

Openssl/get_issuer_entry_count(self:X509) -> integer

get_issuer_entry_count(self) return the amount of entry in the issuer distinguished name (DN) of the given certificate.

Openssl/get_pubkey(self:X509) -> key

get_pubkey(self) returns the public key of a the given certificate.

Openssl/get_recipients(self:PKCS7, possibles:list[X509]) -> list[X509]

finds among possibles for a list of matching certificate that are recipient of the given (enveloped) PKCS#7 get_recipients(self, possibles) return a sublist of the supplied list of possible recipients of the given PKCS#7.

Openssl/get_serial(self:X509) -> integer

get_serial(self) returns the serial number of the given certificate.

Openssl/get_signers(self:PKCS7) -> list[X509]

get_signers(self) extracts the list of signer certificates from the given PKCS#7.

Openssl/get_subject(self:X509) -> string

get_subject(self) return the an subject's DN in the form "/CN=val/field=val...".

Openssl/get_subject_entry(self:X509, field:string) -> string

get_subject_entry(self, field) returns the subject's DN entry value for the given field name.

Openssl/get_subject_entry_count(self:X509) -> integer

get_subject_entry_count(self) returns the amount of entry the subject distinguished name (DN) of the given certificate.

Openssl/get_version(self:X509) -> integer

get_version(self) returns the X509 version of the given certificate the version should be in (0 .. 2) i.e. (v1 .. v3).

Openssl/i2d(self:X509) -> string

i2d(self) creates a DER encoded version of the given certificate.

Openssl/i2d(self:key, pass:string) -> string

i2d(self, pass) is equivalent to i2d(self, "des-cbc", pass).

Openssl/i2d(self:key, algo:CYPHERS, pass:string) -> string

i2d(self, algo, pass) creates a password protected PKCS#8 DER encoded version of the given private key. algo specifies the algorithm used for the key encrytption.

Openssl/i2d(self:X509, pkey:key, name:string, pass:string) -> string

i2d(self, pkey, name, pass) generate a DER encoded PKCS#12. PKCS#12 are used to store an X509 public certificate and its associated private key. The generated PKCS12 is encrypted with the given password pass.

Openssl/i2d_private(self:key) -> string

i2d_private(self) returns a string containing a DER encoded version of the private key of the given key pair.

Openssl/i2d_public(self:key) -> string

i2d_public(self) returns a string containing a DER encoded version of the public key of the given key pair.

Openssl/key_size(self:key) -> integer

key_size(self:key) returns the size of the given key.

Openssl/key_type(self:key) -> string

key_type(self:key) returns the type of the given key which either "RSA", "DSA" or "DH", otherwise "<UNKNOWN KEY TYPE>" is returned.

Openssl/load_X509_pem(pem_file:string) -> list[X509]

load_X509_pem(pem_file) loads a list of certificate from a file of concatened PEM endoded X509 certificates.

Openssl/pem2private(pem:string) -> key

pem2private(pem) decodes a PEM encoded private key.

Openssl/pem2private(pem:string, pass:string) -> key

pem2private(pem) decodes a PEM pasword encoded private key.

Openssl/pem2public(pem:string) -> key

pem2public(pem) decodes a PEM encoded public key.

Openssl/pem2X509(pem:string) -> X509

pem2X509(pem) creates a certificate from a PEM encoded version.

Openssl/private2pem(self:key) -> string

private2pem(self, algo, pass) returns a string containing a PEM encoded version of the private key of the given key pair.

Openssl/private2pem(self:key, algo:CYPHERS, pass:string) -> string

private2pem(self, algo, pass) returns a string containing a PEM password encoded version of the private key of the given key pair.

Openssl/public2pem(self:key) -> string

public2pem(self) returns a string containing a PEM encoded version of the public key of the given key pair.

Openssl/rsa!(nbits:integer) -> key

rsa!(nbits) generates an RSA key pair (private and public keys) of the given size nbits. nbits should be a 2 exponent.

Openssl/save_X509_pem(self:X509, pem_file:string) -> void

save_X509_pem(self, pem_file) saves a PEM encoded certificate in a file.

sclient!(addr:string, p:integer) -> ssl_socket

sclient!(addr, p) creates an SSL socket connected to the server with address addr on the port p.

Openssl/set_authority_info_access(self:X509, authority_info_access:string) -> void

The authority information access extension gives details about how to access certain information relating to the CA. Its syntax is accessOID;location where location has the same syntax as subject alternative name (except that email:copy is not supported). accessOID can be any valid OID but only certain values are meaningful, for example OCSP and caIssuers. Example:

• authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
• authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html

Openssl/set_authority_key_identifier(self:X509, authority_key_identifier:string) -> void

The authority key identifier extension permits two options. keyid and issuer: both can take the optional value ``always''.

If the keyid option is present an attempt is made to copy the subject key identifier from the parent certificate. If the value ``always'' is present then an error is returned if the option fails.

The issuer option copies the issuer and serial number from the issuer certificate. This will only be done if the keyid option fails or is not included unless the ``always'' flag will always include the value. Example:

• authorityKeyIdentifier=keyid,issuer

Openssl/set_basic_constraints(self:X509, basic_constraints:string) -> void

This is a multi valued extension which indicates whether a certificate is a CA certificate. The first (mandatory) name is CA followed by TRUE or FALSE. If CA is TRUE then an optional pathlen name followed by an non-negative value can be included. Example:

• basicConstraints=CA:TRUE
• basicConstraints=CA:FALSE
• basicConstraints=critical,CA:TRUE, pathlen:0

The pathlen parameter indicates the maximum number of CAs that can appear below this one in a chain. So if you have a CA with a pathlen of zero it can only be used to sign end user certificates and not further CAs.

Openssl/set_crl_distribution_points(self:X509, clr_distribution_points:string) -> void

This is a multi-valued extension that supports all the literal options of subject alternative name. Of the few software packages that currently interpret this extension most only interpret the URI option.

Currently each option will set a new DistributionPoint with the fullName field set to the given value.

Other fields like cRLissuer and reasons cannot currently be set or displayed: at this time no examples were available that used these fields. Examples:

• crlDistributionPoints = URI:http://myhost.com/myca.crl
• crlDistributionPoints = URI:http://my.com/my.crl,URI:http://oth.com/my.crl

Openssl/set_issuer(self:X509, issuer:X509) -> void

set_issuer(self, issuer) sets the issuer certificate for a new one. The issuer DN is updated with the subject DN of the issuer you need to call it before adding v3 extension in order to create a root CA you will call set_issuer with issuer = self.

Openssl/set_issuer_alt_name(self:X509, issuer_alt_name:string) -> void

The issuer alternative name option supports all the literal options of subject alternative name. It does not support the email:copy option because that would not make sense. It does support an additional issuer:copy option that will copy all the subject alternative name values from the issuer certificate (if possible). Example:

• issuserAltName = issuer:copy

Openssl/set_key_usage(self:X509, key_usage:string) -> void

Key usage is a multi valued extension consisting of a list of names of the permitted key usages.

The supporte names are: digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly and decipherOnly. Examples:

• keyUsage=digitalSignature, nonRepudiation
• keyUsage=critical, keyCertSign

• digitalSignature : The digitalSignature bit is asserted when the subject public key is used with a digital signature mechanism to support security services other than non-repudiation (bit 1), certificate signing (bit 5), or revocation information signing (bit 6). Digital signature mechanisms are often used for entity authentication and data origin authentication with integrity.
• nonRepudiation : The nonRepudiation bit is asserted when the subject public key is used to verify digital signatures used to provide a non- repudiation service which protects against the signing entity falsely denying some action, excluding certificate or CRL signing.
• keyEncipherment : The keyEncipherment bit is asserted when the subject public key is used for key transport. For example, when an RSA key is to be used for key management, then this bit shall asserted.
• dataEncipherment : The dataEncipherment bit is asserted when the subject public key is used for enciphering user data, other than cryptographic keys.
• keyAgreement : The keyAgreement bit is asserted when the subject public key is used for key agreement. For example, when a Diffie-Hellman key is to be used for key management, then this bit shall asserted.
• keyCertSign : The keyCertSign bit is asserted when the subject public key is used for verifying a signature on certificates. This bit may only be asserted in CA certificates.
• cRLSign : The cRLSign bit is asserted when the subject public key is used for verifying a signature on revocation information (e.g., a CRL).
• encipherOnly : The meaning of the encipherOnly bit is undefined in the absence of the keyAgreement bit. When the encipherOnly bit is asserted and the keyAgreement bit is also set, the subject public key may be used only for enciphering data while performing key agreement.
• decipherOnly : The meaning of the decipherOnly bit is undefined in the absence of the keyAgreement bit. When the decipherOnly bit is asserted and the keyAgreement bit is also set, the subject public key may be used only for deciphering data while performing key agreement.

Openssl/set_not_after(self:X509, days:integer) -> void

set_not_after(self, days) sets the given certificate's expiration date as a number a days from now

Openssl/set_not_before(self:X509, days:integer) -> void

set_not_before(self, days) sets the given certificate's starting validity date as a number a days from now (days can be negative)

Openssl/set_serial(self:X509, serial:integer) -> void

set_serial(self, serial) sets the serial number attribute of the given certificate.

Openssl/set_subject_alt_name(self:X509, subject_alt_name:string) -> void

The subject alternative name extension allows various literal values to be included in the configuration file. These include email (an email address) URI a uniform resource indicator, DNS (a DNS domain name), RID (a registered ID: OBJECT IDENTIFIER), IP (an IP address), dirName (a distinguished name) and otherName.

The email option include a special 'copy' value. This will automatically include and email addresses contained in the certificate subject name in the extension.

The IP address used in the IP options can be in either IPv4 or IPv6 format.

The value of dirName should point to a section containing the distinguished name to use as a set of name value pairs. Multi values AVAs can be formed by preceeding the name with a + character.

otherName can include arbitrary data associated with an OID: the value should be the OID followed by a semicolon and the content in standard ASN1_generate_nconf() format. Example:

• subjectAltName = email:copy,email:my@other.address,URI:http://my.url.here/
• subjectAltName = IP:192.168.7.1
• subjectAltName = IP:13::17
• subjectAltName = email:my@other.address,RID:1.2.3.4
• subjectAltName = otherName:1.2.3.4;UTF8:some other identifier
• subjectAltName = dirName:dir_sect

• C=UK
• O=My Organization
• OU=My Unit
• CN=My Name

Openssl/set_subject_key_identifier(self:X509, subject_key_identifier:string) -> void

This is really a string extension and can take two possible values. Either the word hash which will automatically follow the guidelines in RFC3280 or a hex string giving the extension value to include. The use of the hex string is strongly discouraged. Example:

• subjectKeyIdentifier=hash

Openssl/set_version(self:X509, ver:{0, 1, 2}) -> void

set_version(self, ver) sets the version of the given certificate (v1 is 0, v2 1 and v3 2).

Openssl/sign(self:X509, k:key) => void

sign(self, k) is equivalent to sign(self, k, "sha1").

Openssl/sign(self:DIGEST_ALGORYTHMS, msg:string, k:key) -> string

Calculates a signature value for a given message msg. It is equivalent to :

let ctx := Openssl/digest_context!(algo)  in (Openssl/sign_init(ctx),      Openssl/sign_update(ctx, msg),      Openssl/sign_final(ctx, k))

Openssl/sign(self:X509, k:key, algo:DIGEST_ALGORYTHMS) -> void

sign(self, k, algo) signs a certificate with a private key this should be the last operation made on the certificate, any other update on the data structure would invalidate the object's signature (i.e verify would failed).

Openssl/sign(signer:X509, pkey:key, chain:list[X509], data:port) -> PKCS7

sign(signer, pkey, chain, data) generates a PKCS#7 object with a signed content made of what can be read on data. chain may contain a list of certificates that are needed for chain validation.

Openssl/sign&encrypt(signer:X509, pkey:key, chain:list[X509], recipients:list[X509], data:port) -> PKCS7

sign&encrypt(signer, pkey, chain, recipients, data) generate a signed and encryted PKCS#7 as used by the smime proptocol. The purpose of this method is to generate an encrypted content which has an identified issuer and that can be read by only a set of recipients. The content is made of the data that can be read on the port data. chain represents a list of intermediate (CA) certificates used for verification at the time it is decrypted.

Openssl/sign_filter!(self:port, algo:DIGEST_ALGORYTHMS) -> sign_filter

sign_filter!(self, algo) creates filter that internaly manage a digest context intended for digital signature. Everything written through this filter is used to update the internal state of the digest. Once the returned filter is closed one can obtained a digital signature of the content with sign_final :

let b := blob!(),      signer := Openssl/sign_filter!(b, "sha")  in (fwrite(signer, "some messages"),          fclose(signer),          let digest := sign_final(signer, k)          in (...))

where k is a private key used to sign the digest value.

Openssl/sign_final(self:digest_context, k:key) -> string

sign_final(self, k) finilize the internal state of the digest context initialized with sign_init and return the signature value which is encoded with the given private key k.

Openssl/sign_final(self:sign_filter, k:key) -> string

sign_final(self, k) returns a digital signature of the data that have been written through the filter self, the signature is encrytpted with the given private key k. sign_final should be used once the filter has been closed.

Openssl/sign_init(self:digest_context) -> void

sign_init(self) initialise a digest context for digital signature purpose.

Openssl/sign_update(self:digest_context, msg:string) -> void

sign_update(self, msg) update the internal state of the digest context initialized with sign_init with the addition of the given message msg.

Openssl/verify(self:X509, k:key) -> boolean

verify(self, k) verifies that the key k was the one that signed the certificate.

Openssl/verify(self:X509, trusted:list[X509], untrusted:list[X509]) => boolean

verify(self, trusted, untrusted) is equivalent to verify(self, trusted, untrusted, {}, "any").

Openssl/verify(self:PKCS7, trusted:list[X509], untrusted:list[X509], p:port) -> boolean

verify(self, trusted, untrusted, p) verifies the signature of a PKCS#7 object with a signed content. trusted contains a list of certificates that are trusted by the user of the method and untrusted a list of certificate needed for the whole chain validation. On return, p contains the data that have been signed. The return value is either true if the signer certificate could be verified or false otherwise. In the later case self.verify_message contain the reason why the verification failed.

Openssl/verify(self:DIGEST_ALGORYTHMS, msg:string, signature:string, k:key) -> boolean

Calculates a signature value for a given message msg and verifies that it matches the given digital signature for the given public key k.

let ctx := Openssl/digest_context!(algo)  in (Openssl/verify_init(ctx),      Openssl/verify_update(ctx, msg),      Openssl/verify_final(ctx, signature, k))

Openssl/verify(self:X509, trusted:list[X509], untrusted:list[X509], flags:subtype[VERIFY_FLAGS], purpose:VERIFY_PURPOSE) -> boolean

General verifying process that support flags and purpose. Trusted is typicaly filled with local trusted CA certificates whereas untrusted is a chain of externaly supplied certificates that di facto can't be trusted. true is returned if the verification succeded and false is returned otherwise. In the later case one can get the information why the verification failed in self.verify_message.

Openssl/verify_filter!(self:port, algo:DIGEST_ALGORYTHMS) -> verify_filter

verify_filter!(self, algo) creates filter that internaly manage a digest context intended for digital signature verification. Everything written through this filter is used to update the internal state of the digest. Once the returned filter is closed one can verify that the digest value is a valid digital signature with verify_final :

let b := blob!(),      signer := Openssl/verify_filter!(b, "sha")  in (fwrite(signer, "some messages"),      fclose(signer),      if not(verify_final(signer, sig, k))          error("Invalid signature"),      ...)

where k is a public key used to verify that the digest value matches the supplied digital signature sig.

Openssl/verify_final(self:verify_filter, digest:string, k:key) -> boolean

verify_final(self, digest, k) verifies for the public key k whether the supplied signature sig matches the internal value of the digest calculated with the data that were written through the filter self. verify_final should be used only once the filter has been closed.

Openssl/verify_final(self:digest_context, digest:string, k:key) -> boolean

verify_final(self, digest, k) finilize the internal state of the digest context initialized with verify_init an return true if the given digital signature digest verifies the internal calculated signature for the given public key k.

Openssl/verify_init(self:digest_context) -> void

verify_init(self) initialise a digest context for digital signature verification purpose.

Openssl/verify_update(self:digest_context, msg:string) -> void

verify_update(self, msg) update the internal state of the digest context initialized with verify_init with the addition of the given message msg.

Openssl/X509!(k:key) -> X509

X509!(k) construct a new X509 v3 certificate associated to the given public key.

Openssl/X5092pem(self:X509) -> string

X5092pem(self) returns a PEM encoded version of the given certificate.