Module Netx509_pubkey

module Netx509_pubkey: sig .. end

X.509 public key cryptography - keys and naming

Support for reading in public keys and retrieving the type of the key. This module is mostly about naming key types and algorithms.

In the X.509 standard a public key is often part of a certificate and there stored in the subjectPublicKeyInfo field. However, "raw" public keys (i.e. outside certificates) are also known. In this case, the same representation as for subjectPublicKeyInfo field is chosen and just stored separately in a file.

Like certificates, public keys are described by an ASN.1 syntax and are normally stored by applying the DER encoding rules. If stored in files, PEM headers for the DER encoding are common. Such files have a PEM header of "BEGIN PUBLIC KEY". Note that the header - unlike for private keys - does not indicate the type of key. The type is already a member of the subjectPublicKeyInfo field.

A public key consists of three parts:

the OID of the type of the key
the parameters of the algorithm
the key data

A certain type of public key can only be used with certain algorithms. Often, the OID for the type of the key is simply set to the OID for the simplest algorithm that can be used with the key. For example, RSA keys have the OID of the PKCS-1 encryption algorithm. However, you can use the same keys also with the slightly more complicated PKCS-1 signing algorithms.

It depends on the algorithm whether the parameters can be changed while keeping the key data.

See Netx509_pubkey_crypto for functions that actually encrypt or sign data with the current crypto provider.

type oid = Netoid.t

OIDs are just integer sequences

type alg_id =

|

Alg_id of oid * Netasn1.Value.value option

(*

Algorithms are identified by an OID and OID-specific parameters.

*)

type pubkey = {

	`pubkey_type : alg_id;`
	`pubkey_data : Netasn1.Value.bitstring_value;`

}

Public key info: the key as such plus the algorithm. This combination is stored in PEM files tagged with "PUBLIC KEY", and also part of X.509 certificates.

type hash_function = [ `SHA_1 | `SHA_224 | `SHA_256 | `SHA_384 | `SHA_512 ]

type maskgen_function = [ `MGF1 of hash_function ]

type alg_param =

`\|`	`P_PSS of hash_function * maskgen_function * int`
`\|`	`P_OAEP of hash_function * maskgen_function * string`

type encrypt_alg =

|

Encrypt of oid * alg_param option

(*

An algorithm that can be used for encryption. Same format as Alg_id

*)

type sign_alg =

|

Sign of oid * alg_param option

(*

An algorithm that can be used for signing. Same format as Alg_id

*)

type kex_alg =

|

Kex of oid * alg_param option

(*

An algorithm that can be used for key agreement. Same format as Alg_id

Remember that you can use any key agreement protocol also as public key mechanism: if Alice sends Bob message A based on a secret a, and Bob replies with message B based on a secret b, and both agree on a key K=f(a,b), you can consider A as the public key and Alices's secret a as the private key. The message B is a parameter of the ciphertext (comparable to the IV in symmetric cryptography), and K is used as transport key (for a symmetric cipher). That's why the key agreement algorithms appear here.

*)

val decode_pubkey_from_der : string -> pubkey

Decodes a DER-encoded public key info structure. Note that this function performs only a partial check on the integrity of the data.

val encode_pubkey_to_der : pubkey -> string

Encodes a public key info structure as DER

val read_pubkey_from_pem : Netchannels.in_obj_channel -> pubkey

Reads a PEM file tagged as "PUBLIC KEY". Note that this function performs only a partial check on the integrity of the data.

type privkey =

|

Privkey of string * string

(*

(format,data), using the formats: "RSA", "DSA", "DH", "EC". The data string is for the mentioned formats DER-encoded.

*)

val read_privkey_from_pem : Netchannels.in_obj_channel -> privkey

Reads a PEM file tagged as "... PRIVATE KEY". This function cannot handle encrypted private keys. Note that this function performs only a partial check on the integrity of the data.

module Key: sig .. end

module Encryption: sig .. end

module Keyagreement: sig .. end

module Signing: sig .. end

This web site is published by Informatikbüro Gerd Stolpmann

Plasma	GitLab	Archive
Projects	Blog	Knowledge