(* SPDX-License-Identifier: LGPL-3.0-only *)

type t
type sub_auths = Stdint.Uint32.t array

val create : ?sa:Stdint.Uint32.t array -> Stdint.Uint64.t -> t option
(** [create sas ia] constructs a SID with the identifier authority [ia]
    and, optionally, the subauthorities [sas]. The operation will return
    [None] if [sa] contains more than fifteen subauthorities. *)

val create_unsafe : Stdint.Uint32.t array -> Stdint.Uint64.t -> t
(** [create_unsafe sas ia] constructs a SID with the identifier authority [ia]
    and, optionally, the sub authorities [sas] without validating the inputs.
    Use with caution. *)

val equal : t -> t -> bool
(** [equal sa sb] tests whether [sa] and [sb] are identical. *)

val equal_sub_auths : Stdint.Uint32.t array -> Stdint.Uint32.t array -> bool
(** [equal_sub_auths sa sb] tests whether [sa] and [sb] have identical
    subauthorities. *)

val get_ident_auth : t -> Stdint.Uint64.t
(** [get_ident_auth s] get the identifier authority of SID [s]. *)

val get_sub_auths : t -> sub_auths
(** [get_ident_auth s] get the subauthorities array of SID [s]. *)

(** Conversions to and from the {e string format syntax} (MS-DTYP 2.4.2.1). *)
module StringFmt :
  sig
    val decode : string -> (t, string) result
    (** [decode b] parse string buffer [b] into a SID. *)

    val encode : t -> string
    (** [encode s] convert SID [s] to its string representation. *)
  end

(** Conversion to and from the {e packet representation} (MS-DTYP 2.4.2.2). *)
module PacketRep :
  sig
    type endian = Big | Little
    val decode : ?endian:endian -> bytes -> (t, string) result
    (** [decode endian b] decode the byte buffer [b] as a SID. *)

    val encode : ?endian:endian -> t -> bytes
    (** [encode endian s] convert SID [s] to the packet representation
        encoding subauthorities in endianness [endian]. *)
  end

(** Pre-defined SID constansts and constructors with fixed identifier
    authority (MS-DTYP 2.4.2.4). *)
module WellKnown :
  sig
    val null : t
    val everyone : t
    val world : t
    val local : t
    val creator_owner_id : t
    val creator_group_id : t
    val elite : t

    module Prefix :
      sig
        type toplevel_auth = ?sa:sub_auths -> unit -> t

        val security_null_sid_authority    : toplevel_auth
        val security_world_sid_authority   : ?sa:sub_auths -> unit -> t
        val security_local_sid_authority   : ?sa:sub_auths -> unit -> t
        val security_creator_sid_authority : ?sa:sub_auths -> unit -> t
        val security_nt_authority          : ?sa:sub_auths -> unit -> t
        val security_app_package_authority      : ?sa:sub_auths -> unit -> t
        val security_mandatory_label_authority  : ?sa:sub_auths -> unit -> t
        val security_scoped_policy_id_authority : ?sa:sub_auths -> unit -> t
        val security_authentication_authority   : ?sa:sub_auths -> unit -> t
      end
  end

val of_string : string -> (t, string) result
(** [of_string b] is an alias for [StringFmt.decode b]. *)

val to_string : t -> string
(** [to_string s] is an alias for [StringFmt.encode s]. *)