libocamlnet-ocaml-dev 3.7.3-4 / usr / lib / ocaml / netmech-scram / netmech_scram.mli

(* $Id: netmech_scram.mli 1560 2011-03-04 22:05:14Z gerd $ *)

(** SCRAM mechanism for authentication (RFC 5802) *)

(** This implements SCRAM-SHA-1 for GSSAPI. Other profiles may be added later.

    As we do not implement SASLprep, usernames and passwords are restricted
    to US-ASCII.
 *)

type ptype = [ `GSSAPI ]
  (** Currently only the variant for [`GSSAPI] is supported *)

type mechanism = [ `SHA_1 ]

type profile =
    { ptype : ptype;
      mechanism : mechanism;       (** Which mechanism *)
      return_unknown_user : bool;  (** Whether servers exhibit the fact that the
				       user is unknown *)
      iteration_count_limit : int; (** Largest supported iteration number *)
    }
  (** Profile *)


type server_error =
    [ `Invalid_encoding
    | `Extensions_not_supported
    | `Invalid_proof
    | `Channel_bindings_dont_match
    | `Server_does_support_channel_binding
    | `Channel_binding_not_supported
    | `Unsupported_channel_binding_type
    | `Unknown_user
    | `Invalid_username_encoding
    | `No_resources
    | `Other_error
    | `Extension of string
    ]
  (** Error codes of this protocol *)

type client_session
  (** Session context for clients *)


type server_session
  (** Session context for servers *)


exception Invalid_encoding of string * string
  (** Raised by clients when something cannot be decoded. First string
      is an error message, the second string the raw message that cannot
      be decoded
   *)

exception Invalid_username_encoding of string * string
  (** Raised by clients when the username does not match the requirements.
      Arguments as for [Invalid_encoding].
   *)

exception Extensions_not_supported of string * string
  (** Raised by clients when the server enables an unsupported extension.
      Arguments as for [Invalid_encoding].
   *)

exception Protocol_error of string
  (** Raised by clients when the server violates the protocol. The argument
      is a message.
   *)

exception Invalid_server_signature
  (** Raised by clients when the signature sent by the server is invalid
      (i.e. the server does not know the client password)
   *)

exception Server_error of server_error
  (** Raised by clients when the server sent an error code *)


val profile : ?return_unknown_user:bool -> ?iteration_count_limit:int ->
              ptype -> profile
  (** Creates a profile *)

val string_of_server_error : server_error -> string
val server_error_of_string : string -> server_error
  (** Conversion *)


(** {2 Clients} *)

(** The idea is to create a client session [s] first. The functions
    [client_emit_flag] and [client_recv_flag] indicate now whether
    the client needs to emit a new message, or whether it needs to
    receive a message, respectively. Emission is done by [client_emit_message],
    reception by [client_recv_message]. If everything goes well, the
    protocol state advances, and finally [client_finish_flag] is true.
    This indicates that the client is authenticated and that the server
    knows the client's password. If an error occurs, an exception is
    raised (see above for possibilities), and [client_error_flag] signals
    [true].
 *)

val create_client_session : profile -> string -> string -> client_session
  (** [create_client_session p username password]: Creates a new client
      session for profile [p] so that the client authenticates as user
      [username], and proves its identify with the given [password].
   *)

val client_configure_channel_binding : client_session -> string -> unit
  (** Instruct the client to require a channel binding. The passed string
      is the [c] parameter (before encoding it via Base64. The function
      needs to be called before sending the second message to the server.
      It fails if called too late.
   *)
(* SASL: The string would have to include the gs2-header. For a SASL-enabled
   profile we would need some additional functions
   (client_negotiate_channel_binding).
 *)

val client_emit_flag : client_session -> bool
  (** Whether [client_emit_message] can now be called *)

val client_recv_flag : client_session -> bool
  (** Whether [client_recv_message] can now be called *)

val client_finish_flag : client_session -> bool
  (** Whether the client is authenticated and the server verified *)

val client_error_flag : client_session -> bool
  (** Whether an error occurred, and the protocol cannot advance anymore *)

val client_channel_binding : client_session -> string
  (** Returns the channel binding ("" of none) *)

val client_emit_message : client_session -> string
  (** Emits the next message to be sent to the server *)

val client_recv_message : client_session -> string -> unit
  (** Receives the next message from the server *)

val client_protocol_key : client_session -> string option
  (** The 128-bit protocol key for encrypting messages. This is available 
      as soon as the second client message is emitted.
   *)

val client_user_name : client_session -> string
  (** The user name *)

val client_export : client_session -> string
val client_import : string -> client_session
  (** Exports a client session as string, and imports the string again.
      Only established sessions are allowed to be exported
      (for which [client_finish_flag] is true).

      The export format is just a marshalled Ocaml value.
   *)


(** {2 Servers} *)

(** The idea is to create a server session [s] first. The functions
    [server_emit_flag] and [server_recv_flag] indicate now whether
    the server needs to emit a new message, or whether it needs to
    receive a message, respectively. Emission is done by [server_emit_message],
    reception by [server_recv_message]. If everything goes well, the
    protocol state advances, and finally [server_finish_flag] is true.
    This indicates that the client could be authenticated.

    If an error occurs, {b no} exception is raised, and the protocol
    advances nevertheless, and finally the server sends an error token
    to the client. After this, [server_error_flag] returns true.
 *)


val create_server_session : 
      profile -> (string -> string * string * int) -> server_session
  (** [create_server_session p auth]: Creates a new server session with
      profile [p] and authenticator function [auth].

      The function is [auth] is called when the credentials of the
      client have been received to check whether the client can be
      authenticated. It is called as

      {[
      let (salted_password, salt, iteration_count) = auth username
      ]}

      where [username] is the user name. The function can now raise
      [Not_found] if the user is unknown, or it can return the
      shown triple. Note that the cleartext password needs not to
      be known. [salt] is a random string, and [iteration_count] a
      security parameter that should be at least 4096. Whereas [salt]
      should be different for each user, the [iteration_count] can be
      chosen as a constant (e.g. 4096). Now [salted_password] can be
      computed from the cleartext password and these two extra parameters.
      See [salt_password] below.
   *)

val create_salt : unit -> string
  (** Creates a random string suited as salt *)

val salt_password : string -> string -> int -> string
  (** [let salted_password = salt_password password salt iteration_count]

      As we do not implement [SASLprep] only passwords consisting of
      US-ASCII characters are accepted ([Invalid_encoding] otherwise).
   *)

val server_emit_flag : server_session -> bool
  (** Whether [server_emit_message] can now be called *)

val server_recv_flag : server_session -> bool
  (** Whether [server_recv_message] can now be called *)

val server_finish_flag : server_session -> bool
  (** Whether the client is authenticated *)

val server_error_flag : server_session -> bool
  (** Whether an error occurred, and the protocol cannot advance anymore *)

val server_emit_message : server_session -> string
  (** Emits the next message to be sent to the client *)

val server_recv_message : server_session -> string -> unit
  (** Receives the next message from the client *)

val server_protocol_key : server_session -> string option
  (** The 128-bit protocol key for encrypting messages. This is available 
      as soon as the second client message has been received.
   *)

val server_channel_binding : server_session -> string option
  (** Returns the channel binding requirement (the "c" parameter). It is
      up to the application to enforce the binding. This information is 
      available as soon as the second client message has been received
   *)

val server_user_name : server_session -> string option
  (** The user name as transmitted from the client. This is returned here
      even before the authentication is completed!
   *)

val server_export : server_session -> string
val server_import : string -> server_session
  (** Exports a server session as string, and imports the string again.
      Only established sessions are allowed to be exported
      (for which [server_finish_flag] is true).

      The export format is just a marshalled Ocaml value.
   *)


(** {2 Confidentiality} *)

type specific_keys =
    { kc : string;
      ke : string;
      ki : string
    }
  (** The specific keys to use *)

(** This module implements AES in Ciphertext Stealing mode (see RFC 3962) *)
module AES_CTS : sig
  val c : int
  val m : int
  val encrypt : string -> string -> string
  val encrypt_mstrings : 
    string -> Xdr_mstring.mstring list -> Xdr_mstring.mstring list
  val decrypt : string -> string -> string
  val decrypt_mstrings : 
    string -> Xdr_mstring.mstring list -> Xdr_mstring.mstring list
  val tests : (string * string * string) list
  val run_tests : unit -> bool
  val run_mtests : unit -> bool
end


(** This is the cryptosystem as defined in RFC 3961, so far needed here.
    This uses [AES_CTS] as cipher, and SHA1-96 for signing.
 *)
module Cryptosystem : sig
  exception Integrity_error

  val derive_keys : string -> int -> specific_keys
    (** [derive_keys protocol_key usage]: Returns the specific keys for
	this [protocol_key] and this [usage] numbers. See RFC 4121 for
	applicable usage numbers
     *)

  val encrypt_and_sign :  specific_keys -> string -> string
    (** Encrypts the plaintext message and adds a signature to the
	ciphertext.

	Returns [ciphertext_with_signature].
     *)

  val encrypt_and_sign_mstrings : 
         specific_keys -> Xdr_mstring.mstring list -> Xdr_mstring.mstring list
    (** Same, but with data representation as [mstring list] *)

  val decrypt_and_verify :  specific_keys -> string -> string
    (** Decrypts the ciphertext and verifies the attached signature.
	Returns the restored plaintext. 

	For very short plaintexts (< 16 bytes) there will be some
	padding at the end ("residue"), as returned as [ec] above.
	We ignore this problem generally,
	because GSS-API adds a 16-byte header to the plaintext anyway,
	so these short messages do not occur.

	If the signature is not valid, the exception [Integrity_error]
	is raised.
     *)

  val decrypt_and_verify_mstrings :
         specific_keys -> Xdr_mstring.mstring list -> Xdr_mstring.mstring list
    (** Same, but with data representation as [mstring list] *)

  val get_ec : specific_keys -> int -> int
    (** [let ec = get_ec e_keys n]:
        Returns the required value for the "extra count" field of
	RFC 4121 if the plaintext message has size [n]. Here,
	[n] is the size of the payload message plus the token
	header of 16 bytes, i.e. the function is always called with
	[n >= 16].

	Here, the returned [ec] value is always 0.
     *)

  val get_mic : specific_keys -> string -> string
    (** Returns a message integrity code *)

  val get_mic_mstrings :
         specific_keys -> Xdr_mstring.mstring list -> string
    (** Same, but with data representation as [mstring list] *)
end


module Debug : sig
  val enable : bool ref
    (** Enable debugging of this module *)
end