(* SPDX-License-Identifier: LGPL-3.0-only WITH OCaml-LGPL-linking-exception *)

(** Security identifiers.

    {e Sid} implements the “Security Identifier” data type commonly used
    on the Microsoft Windows platform. When processing input, it tries to
    adhere as closely to the specification as possible. Optionally, a
    special mode for the text representation is available as the
    {e MSStringFmt} module which aims to be bug-for-bug compatible with
    the official implementation. There is no such mode for the two identical
    binary representations due to the fact that they don’t leave room for
    ambiguity.

    @see <https://msdn.microsoft.com/en-us/library/cc230371.aspx> the relevant
    section in the {e [MS-DTYP]} compilation of types. *)

type t
type sub_auths = Stdint.Uint32.t array

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

val create_unsafe : Stdint.Uint64.t -> Stdint.Uint32.t array -> t
(** [create_unsafe sas ia] constructs a SID with the identifier authority [ia]
    and 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

(** Conversions to and from the {e string format syntax} with permissive
    input validation. *)
module MSStringFmt :
  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
    (** Specify the endianness when internalizing integers. Only relevant for
        subauthorities as the identifier authority is specified as big endian.
        The default is always [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]. *)

    val from_channel : ?endian:endian -> in_channel -> (t, string) result
    (** [from_channel endian ic] read binary SID from [ic] with endianness
        [endian]. *)

    val to_channel : ?endian:endian -> out_channel -> t -> unit
    (** [to_channel endian oc s] write SID [s] in packet representation
        to channel [oc] with endianness [endian]. *)
  end

(** Pre-defined SID constants and constructors with fixed identifier
    authority (MS-DTYP 2.4.2.4). *)
module WellKnown :
  sig
    val null : t
    (** The SID {e S-1-0-0}. *)

    val everyone : t
    (** The SID {e S-1-1-0}. *)

    val world : t
    (** Alias for [everyone]. *)

    val local : t
    (** The SID {e S-1-2-0}. *)

    val console_logon : t
    (** The SID {e S-1-2-1}. *)

    val creator_owner_id : t
    (** The SID {e S-1-3-0}. *)

    val creator_group_id : t
    (** The SID {e S-1-3-1}. *)

    val creator_owner_server : t
    (** The SID {e S-1-3-2}. *)

    val creator_group_server : t
    (** The SID {e S-1-3-3}. *)

    val owner_rights : t
    (** The SID {e S-1-3-4}. *)

    val elite : t

    val nt_authority : t
    (** The SID {e S-1-5}.
    
        Note that according to the offical grammar as layed out in MS-DTYP
        2.4.2.1, this SID cannot be converted to “string format” due to its
        lack of subauthorities. However, it is the same document which also
        specifies this SID. How to reconcile the two is left as an exercise
        to the reader. *)

    val dialup : t
    (** The SID {e S-1-5-1}. *)

    val network : t
    (** The SID {e S-1-5-2}. *)

    val batch : t
    (** The SID {e S-1-5-3}. *)

    val interactive : t
    (** The SID {e S-1-5-4}. *)

    val logon_id : t
    (** The SID {e S-1-5-5}. *)

    val service : t
    (** The SID {e S-1-5-6}. *)

    val anonymous : t
    (** The SID {e S-1-5-7}. *)

    val proxy : t
    (** The SID {e S-1-5-8}. *)

    val enterprise_domain_controllers : t
    (** The SID {e S-1-5-9}. *)

    val principal_self : t
    (** The SID {e S-1-5-10}. *)

    val authenticated_users : t
    (** The SID {e S-1-5-11}. *)

    val restricted_code : t
    (** The SID {e S-1-5-12}. *)

    val terminal_server_user : t
    (** The SID {e S-1-5-13}. *)

    val remote_interactive_logon : t
    (** The SID {e S-1-5-14}. *)

    val this_organisation : t
    (** The SID {e S-1-5-15}. *)

    val iusr : t
    (** The SID {e S-1-5-17}. *)

    val local_system : t
    (** The SID {e S-1-5-18}. *)

    val local_service : t
    (** The SID {e S-1-5-19}. *)

    val compounded_authentication : t
    (** The SID {e S-1-5-21-0-0-0-496}. *)

    val claims_valid : t
    (** The SID {e S-1-5-21-0-0-0-497}. *)

    val administrator : Stdint.Uint32.t -> t
    (** [administrator machine] constructs a SID {e S-1-5-21-[machine]-500}. *)

    val guest : Stdint.Uint32.t -> t
    (** [guest machine] constructs a SID {e S-1-5-21-[machine]-501}. *)

    val krbtgt : Stdint.Uint32.t -> t
    (** [krbtgt domain] constructs a SID {e S-1-5-21-[domain]-502}. *)

    val domain_admins : Stdint.Uint32.t -> t
    (** [domain_admins domain] constructs a SID {e S-1-5-21-[domain]-512}. *)

    val domain_users : Stdint.Uint32.t -> t
    (** [domain_users domain] constructs a SID {e S-1-5-21-[domain]-513}. *)

    val domain_guests : Stdint.Uint32.t -> t
    (** [domain_guests domain] constructs a SID {e S-1-5-21-[domain]-514}. *)

    val domain_computers : Stdint.Uint32.t -> t
    (** [domain_computers domain] constructs a SID {e S-1-5-21-[domain]-515}. *)

    val domain_domain_controllers : Stdint.Uint32.t -> t
    (** [domain_domain_controllers domain] constructs a SID
        {e S-1-5-21-[domain]-516}. *)

    val cert_publishers : Stdint.Uint32.t -> t
    (** [cert_publishers domain] constructs a SID {e S-1-5-21-[domain]-517}. *)

    val schema_administrators : Stdint.Uint32.t -> t
    (** [schema_administrators root_domain] constructs a SID
        {e S-1-5-21-[root_domain]-518}. *)

    val enterprise_admins : Stdint.Uint32.t -> t
    (** [enterprise_admins root_domain] constructs a SID
        {e S-1-5-21-[root_domain]-519}. *)

    val group_policy_creator_owners : Stdint.Uint32.t -> t
    (** [group_policy_creator_owners domain] constructs a SID
        {e S-1-5-21-[domain]-520}. *)

    val readonly_domain_controllers : Stdint.Uint32.t -> t
    (** [readonly_domain_controllers domain] constructs a SID
        {e S-1-5-21-[domain]-521}. *)

    val cloneable_controllers : Stdint.Uint32.t -> t
    (** [cloneable_controllers domain] constructs a SID
        {e S-1-5-21-[domain]-522}. *)

    val protected_users : Stdint.Uint32.t -> t
    (** [protected_users domain] constructs a SID {e S-1-5-21-[domain]-525}. *)

    val key_admins : Stdint.Uint32.t -> t
    (** [key_admins domain] constructs a SID {e S-1-5-21-[domain]-526}. *)

    val enterprise_key_admins : Stdint.Uint32.t -> t
    (** [enterprise_key_admins domain] constructs a SID {e S-1-5-21-[domain]-527}. *)

    val ras_servers : Stdint.Uint32.t -> t
    (** [ras_servers domain] constructs a SID {e S-1-5-21-[domain]-553}. *)

    val allowed_rodc_password_replication_group : Stdint.Uint32.t -> t
    (** [allowed_rodc_password_replication_group domain] constructs a SID
        {e S-1-5-21-[domain]-571}. *)

    val denied_rodc_password_replication_group : Stdint.Uint32.t -> t
    (** [denied_rodc_password_replication_group domain] constructs a SID
        {e S-1-5-21-[domain]-572}. *)

    val builtin_administrators : t
    (** The SID {e S-1-5-32-544}. *)

    val builtin_users : t
    (** The SID {e S-1-5-32-545}. *)

    val builtin_guests : t
    (** The SID {e S-1-5-32-546}. *)

    val power_users : t
    (** The SID {e S-1-5-32-547}. *)

    val account_operators : t
    (** The SID {e S-1-5-32-548}. *)

    val server_operators : t
    (** The SID {e S-1-5-32-549}. *)

    val printer_operators : t
    (** The SID {e S-1-5-32-550}. *)

    val backup_operators : t
    (** The SID {e S-1-5-32-551}. *)

    val replicator : t
    (** The SID {e S-1-5-32-552}. *)

    val alias_prew2kcompacc : t
    (** The SID {e S-1-5-32-554}. *)

    val remote_desktop : t
    (** The SID {e S-1-5-32-555}. *)

    val network_configuration_ops : t
    (** The SID {e S-1-5-32-556}. *)

    val incoming_forest_trust_builders : t
    (** The SID {e S-1-5-32-557}. *)

    val perfmon_users : t
    (** The SID {e S-1-5-32-558}. *)

    val perflog_users : t
    (** The SID {e S-1-5-32-559}. *)

    val windows_authorization_access_group : t
    (** The SID {e S-1-5-32-560}. *)

    val terminal_server_license_servers : t
    (** The SID {e S-1-5-32-561}. *)

    val distributed_com_users : t
    (** The SID {e S-1-5-32-562}. *)

    val iis_iusrs : t
    (** The SID {e S-1-5-32-568}. *)

    val cryptographic_operators : t
    (** The SID {e S-1-5-32-569}. *)

    val event_log_readers : t
    (** The SID {e S-1-5-32-573}. *)

    val certificate_service_dcom_access : t
    (** The SID {e S-1-5-32-574}. *)

    val rds_remote_access_servers : t
    (** The SID {e S-1-5-32-575}. *)

    val rds_endpoint_servers : t
    (** The SID {e S-1-5-32-576}. *)

    val rds_management_servers : t
    (** The SID {e S-1-5-32-577}. *)

    val hyper_v_admins : t
    (** The SID {e S-1-5-32-578}. *)

    val access_control_assistance_ops : t
    (** The SID {e S-1-5-32-579}. *)

    val remote_management_users : t
    (** The SID {e S-1-5-32-580}. *)

    val write_restricted_code : t
    (** The SID {e S-1-5-33}. *)

    val ntlm_authentication : t
    (** The SID {e S-1-5-64-10}. *)

    val schannel_authentication : t
    (** The SID {e S-1-5-64-14}. *)

    val digest_authentication : t
    (** The SID {e S-1-5-64-21}. *)

    val this_organization_certificate : t
    (** The SID {e S-1-5-65-1}. *)

    val nt_service : t
    (** The SID {e S-1-5-80}. *)

    val user_mode_drivers : t
    (** The SID {e S-1-5-84-0-0-0-0-0}. *)

    val local_account : t
    (** The SID {e S-1-5-113}. *)

    val local_account_and_member_of_administrators_group : t
    (** The SID {e S-1-5-114}. *)

    val other_organization : t
    (** The SID {e S-1-5-1000}. *)

    val all_app_packages : t
    (** The SID {e S-1-15-2-1}. *)

    val ml_untrusted : t
    (** The SID {e S-1-16-0}. *)

    val ml_low : t
    (** The SID {e S-1-16-4096}. *)

    val ml_medium : t
    (** The SID {e S-1-16-8192}. *)

    val ml_medium_plus : t
    (** The SID {e S-1-16-8448}. *)

    val ml_high : t
    (** The SID {e S-1-16-12288}. *)

    val ml_system : t
    (** The SID {e S-1-16-16384}. *)

    val ml_protected_process : t
    (** The SID {e S-1-16-20480}. *)

    val ml_secure_process : t
    (** The SID {e S-1-16-28672}. *)

    val authentication_authority_asserted_identity : t
    (** The SID {e S-1-18-1}. *)

    val service_asserted_identity : t
    (** The SID {e S-1-18-2}. *)

    val fresh_public_key_identity : t
    (** The SID {e S-1-18-3}. *)

    val key_trust_identity : t
    (** The SID {e S-1-18-4}. *)

    val key_property_mfa : t
    (** The SID {e S-1-18-5}. *)

    val key_property_attestation : t
    (** The SID {e S-1-18-6}. *)

    module Prefix :
      sig
        val security_null_sid_authority : sub_auths -> t
        (** [security_null_sid_authority sub_auths] constructs a SID
            {e S-1-0-[sub_auths]…}. *)

        val security_world_sid_authority : sub_auths -> t
        (** [security_world_sid_authority sub_auths] constructs a SID
            {e S-1-1-[sub_auths]…}. *)

        val security_local_sid_authority : sub_auths -> t
        (** [security_local_sid_authority sub_auths] constructs a SID
            {e S-1-2-[sub_auths]…}. *)

        val security_creator_sid_authority : sub_auths -> t
        (** [security_creator_sid_authority sub_auths] constructs a SID
            {e S-1-3-[sub_auths]…}. *)

        val security_nt_authority : sub_auths -> t
        (** [security_nt_authority sub_auths] constructs a SID
            {e S-1-5-[sub_auths]…}. *)

        val security_app_package_authority : sub_auths -> t
        (** [security_app_package_authority sub_auths] constructs a SID
            {e S-1-15-[sub_auths]…}. *)

        val security_mandatory_label_authority : sub_auths -> t
        (** [security_mandatory_label_authority sub_auths] constructs a SID
            {e S-1-16-[sub_auths]…}. *)

        val security_scoped_policy_id_authority : sub_auths -> t
        (** [security_scoped_policy_id_authority sub_auths] constructs a SID
            {e S-1-17-[sub_auths]…}. *)

        val security_authentication_authority : sub_auths -> t
        (** [security_authentication_authority sub_auths] constructs a SID
            {e S-1-18-[sub_auths]…}. *)
      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]. *)

val of_bytes : ?endian:PacketRep.endian -> bytes -> (t, string) result
(** [of_bytes endian b] is an alias for [PacketRep.decode endian b]. *)

val to_bytes : ?endian:PacketRep.endian -> t -> bytes
(** [to_bytes endian b] is an alias for [PacketRep.encode endian b]. *)