keyring

    Download zip
    Author
    Version
    0.6.0
    License
    Zlib
    Last updated
    4 hours ago
    Downloads
    14

    No dependencies

    #Omochice/keyring

    Four operations on the operating system's credential store, get, set, delete, and list, written as C stubs that reach each platform's library without link flags in the consumer's build, so a consumer adds nothing of its own.

    The module covers the macOS Keychain, the Secret Service through libsecret on Linux, and the Windows Credential Manager. It covers nothing else: no other store, no prompt for a secret, and no policy on what the service and account names mean.

    On macOS the plaintext of a read secret stays in freed memory until it is reused, because CoreFoundation offers no call that wipes a CFData before releasing it. The Linux and Windows stubs wipe the buffer before freeing it.

    #Usage

    The test below stores a secret, reads it back, lists the accounts of its service, and removes it again. Every operation raises KeyringError, which tells a machine without a reachable store (NoStore) apart from a store that rejected the request (Refused). The package supports only the native target, so a consumer has to build for it as well.

    The block is skipped by moon test because it would write to the credential store of whoever runs the tests, but moon check still compiles it.

    ///|
    #skip("touches the OS credential store")
    test "a secret round-trips through the credential store" {
    let service = "my-app"
    let account = "alice@example.com"
    try {
    @keyring.set(service~, account~, secret="s3cret")
    match @keyring.get(service~, account~) {
    Some(secret) => println("found a secret of \{secret.length()} characters")
    None => println("nothing is stored for \{account}")
    }
    for stored in @keyring.list(service) {
    println(stored)
    }
    @keyring.delete(service~, account~)
    } catch {
    NoStore(message) => println("no credential store: \{message}")
    Refused(code) => println("the store refused the operation: \{code}")
    }
    }

    #Omochice/keyring

    Four operations on the operating system's credential store, get, set, delete, and list, written as C stubs that reach each platform's library without link flags in the consumer's build, so a consumer adds nothing of its own.

    The module covers the macOS Keychain, the Secret Service through libsecret on Linux, and the Windows Credential Manager. It covers nothing else: no other store, no prompt for a secret, and no policy on what the service and account names mean.

    On macOS the plaintext of a read secret stays in freed memory until it is reused, because CoreFoundation offers no call that wipes a CFData before releasing it. The Linux and Windows stubs wipe the buffer before freeing it.

    #Usage

    The test below stores a secret, reads it back, lists the accounts of its service, and removes it again. Every operation raises KeyringError, which tells a machine without a reachable store (NoStore) apart from a store that rejected the request (Refused). The package supports only the native target, so a consumer has to build for it as well.

    The block is skipped by moon test because it would write to the credential store of whoever runs the tests, but moon check still compiles it.

    ///|
    #skip("touches the OS credential store")
    test "a secret round-trips through the credential store" {
    let service = "my-app"
    let account = "alice@example.com"
    try {
    @keyring.set(service~, account~, secret="s3cret")
    match @keyring.get(service~, account~) {
    Some(secret) => println("found a secret of \{secret.length()} characters")
    None => println("nothing is stored for \{account}")
    }
    for stored in @keyring.list(service) {
    println(stored)
    }
    @keyring.delete(service~, account~)
    } catch {
    NoStore(message) => println("no credential store: \{message}")
    Refused(code) => println("the store refused the operation: \{code}")
    }
    }

    KeyringError

    pub suberror KeyringError {
    NoStore(String)
    Refused(Int)
    }

    Failure to reach a credential store, or a store refusing one operation.

    #skip("touches the OS credential store")
    test {
    @keyring.set(service="my-app", account="alice", secret="secret") catch {
    NoStore(message) => println(message)
    Refused(code) => println("store refused the write: \{code}")
    }
    }

    INTERNAL

    let INTERNAL : Int

    The Refused payload for a failure of this module itself, such as an allocation failure or a secret that cannot be decoded, which no store reported.

    delete

    fn delete(service~ : String, account~ : String) -> Unit raise KeyringError

    Removes the secret for service and account; does nothing when there is none.

    Raises

    NoStore when no credential store is reachable, Refused when the store rejects the removal.

    #skip("touches the OS credential store")
    test {
    @keyring.delete(service="my-app", account="alice")
    }

    get

    fn get(service~ : String, account~ : String) -> String? raise KeyringError

    Returns the secret stored for service and account, or None when there is none.

    Raises

    NoStore when no credential store is reachable, Refused when the store rejects the read.

    #skip("touches the OS credential store")
    test {
    match @keyring.get(service="my-app", account="alice") {
    Some(token) => ignore(token)
    None => ()
    }
    }

    list

    fn list(service : String) -> Array[String] raise KeyringError

    Returns the accounts that hold a secret under service.

    Raises

    NoStore when no credential store is reachable, Refused when the store rejects the query.

    #skip("touches the OS credential store")
    test {
    for account in @keyring.list("my-app") {
    ignore(account)
    }
    }

    set

    fn set(service~ : String, account~ : String, secret~ : String) -> Unit raise KeyringError

    Stores secret for service and account, replacing any existing one. A secret containing a NUL character is refused with INTERNAL on every platform, because the Secret Service takes a C string and would otherwise store a truncated secret on Linux only.

    Raises

    NoStore when no credential store is reachable, Refused when the store rejects the write or the secret contains NUL.

    #skip("touches the OS credential store")
    test {
    @keyring.set(service="my-app", account="alice", secret="secret")
    }

    Source Files