Plasma GitLab Archive
Projects Blog Knowledge

Module Netx509

module Netx509: sig .. end

X.509 certificates

This module defines a parser for X.509 certificates in Internet context (RFC 5280). The basic structure is implemented, and there are also parsers for the most needed extensions.

There are several involved formats:

  • ASN.1 is the language in which the certificate format is described. When we refer here to ASN.1 we mean tagged values as defined by Netasn1.Value.value.
  • DER is the common binary encoding for ASN.1 values in this context. DER is a subset of BER (which is implemented by Netasn1.decode_ber). The encoding of ASN.1 values in BER is ambiguous, and DER specifies the variant to use in order to get a "distinguished" encoding (that's what the "D" stands for), which is needed to get unique digital signatures.
  • PEM is a set of standards for "privacy enhanced mail". The "PEM encoding" of certificates is simply BASE-64 of DER.
type oid = Netoid.t 

OIDs are just integer sequences

class type directory_name = object .. end

Directory names are also known as distinguished names.

class type x509_certificate = object .. end

An X.509 certificate in decoded form.

OIDs for DN attribute types

module DN_attributes: sig .. end

Distinguished names

module X509_DN_string: Netdn.DN_string 

Parser/printer for distnguished names as they may occur in X.509 certificates

val lookup_dn_ava : directory_name -> oid -> Netasn1.Value.value

Find the first relative DN setting this OID (or Not_found)

val lookup_dn_ava_utf8 : directory_name -> oid -> string

Same as lookup_dn_ava, but additionally converts the value to UTF-8


class x509_dn_from_ASN1 : Netasn1.Value.value -> directory_name

Returns the DN object for a Name entity

class x509_dn_from_string : string -> directory_name

Returns the DN object for an RFC 4514-encoded string

class x509_certificate_from_ASN1 : Netasn1.Value.value -> x509_certificate

Parses the passed ASN.1 value and returns the certificate object

class x509_certificate_from_DER : string -> x509_certificate

Parses the passed DER string and returns the certificate object


Extensions are identified by an OID (found in the following CE module), and the value is a DER-encoded ASN.1 value. The parse_* functions take this DER-encoded value and decode them. E.g. get the "authority key identifier":

  let _, aki_der, _ = 
      (fun (oid,_,_) -> oid = CE.ce_authority_key_identifier) 
      cert#extensions in
  let aki =
    parse_authority_key_identifier aki_der

Or use find_extension, as defined below.

Note that we don't have parsers for all extensions.

module CE: sig .. end
exception Extension_not_found of oid
val find_extension : oid -> (oid * string * bool) list -> string * bool

find_extension is designed to be applied to the result of the extensions method of Netx509.x509_certificate:

  let (data, critical) =
    find_extension CE.ce:authority_key_identifier cert#extensions

It returns the undecoded data string, and the critical flag.

Raises Extension_not_found if there is no such extension.

val check_critical_exts : oid list -> (oid * string * bool) list -> bool

check_critical_exts list exts: When an extension is flagged as critical, it must be processed by the communication endpoint. If there is a critical extension that cannot be processed, this is an error. This function checks whether there are any critical extensions in exts beyond those in list, and returns true in this case.

Use this in software as:

  let unprocessed_critical =
       [ CE.ce_basic_constraints ]

and pass the list of all extension OIDs you actually process. You should raise an error if unprocessed_critical is true.

type general_name = [ `DNS_name of string
| `Directory_name of directory_name
| `Edi_party_name of string option * string
| `IP_address of Unix.socket_domain * Unix.inet_addr * Unix.inet_addr
| `Other_name of oid * Netasn1.Value.value
| `Registered_ID of oid
| `Rfc822_name of string
| `Uniform_resource_identifier of string
| `X400_address of Netasn1.Value.value ]

General names:

  • `Other_name(oid, value): the oid determines the extension name format
  • `Rfc822_name n: an email address n (ASCII encoded)
  • `DNS_name n: an Internet domain n (ASCII encoded - no internationalization)
  • `X400_address v: an X.400 address, which is not decoded here and just given as unparsed ASN.1 value v
  • `Directory_name n: a directory name n (i.e. a name using the syntax of distinguished names)
  • `Edi_party_name(assigner,party), both names as UTF-8
  • `Uniform_resource_identifier uri: this uri (ASCII-encoded, no internationalization)
  • `IP_address(dom,addr,mask): the address with mask
  • `Registered oid: a symbolical pre-registered name known under oid
type authority_key_identifier = {
   aki_key_identifier : string option;
   aki_authority_cert_issuer : general_name list;
   aki_authority_cert_serial_number : string option;
val parse_authority_key_identifier : string -> authority_key_identifier
val parse_subject_key_identifier : string -> string

Returns the key identifier directly

type key_usage_flag = [ `Crl_sign
| `Data_encipherment
| `Decipher_only
| `Digital_signature
| `Encipher_only
| `Key_agreement
| `Key_cert_sign
| `Key_encipherment
| `Non_repudiation ]
val parse_key_usage : string -> key_usage_flag list
val parse_subject_alt_name : string -> general_name list
val parse_issuer_alt_name : string -> general_name list
val parse_subject_directory_attributes : string -> (oid * Netasn1.Value.value list) list
val parse_basic_constraints : string -> bool * int option
type ext_key_usage_flag = [ `Client_auth
| `Code_signing
| `Email_protection
| `OCSP_signing
| `Server_auth
| `Time_stamping
| `Unknown ]
val parse_ext_key_usage : string -> (oid * ext_key_usage_flag) list

Returns the OID as array, and as decoded flag

module KP: sig .. end

Key purpose IDs as returned by parse_ext_key_usage

type authority_access_description_flag = [ `CA_issuers | `OCSP | `Unknown ] 
type subject_access_description_flag = [ `CA_repository | `Time_stamping | `Unknown ] 
type access_description_flag = [ `CA_issuers | `CA_repository | `OCSP | `Time_stamping | `Unknown ] 
val parse_authority_info_access : string ->
(oid * authority_access_description_flag *
val parse_subject_info_access : string ->
(oid * subject_access_description_flag * general_name)
module AD: sig .. end

Generic parsers

val general_name_from_ASN1 : Netasn1.Value.value -> general_name

Parses the general_name structure

val general_names_from_ASN1 : Netasn1.Value.value -> general_name list

Parse a sequence of general names

val directory_string_from_ASN1 : Netasn1.Value.value -> string

Returns the directory_string as UTF-8

val attribute_from_ASN1 : Netasn1.Value.value -> oid * Netasn1.Value.value list

Parses an attribute

val attributes_from_ASN1 : Netasn1.Value.value -> (oid * Netasn1.Value.value list) list

Parses a sequence of attributes

This web site is published by Informatikbüro Gerd Stolpmann
Powered by Caml