github.com/lestrrat-go/jwx/v2@v2.0.21/jws/options.yaml (about)

     1  package_name: jws
     2  output: jws/options_gen.go
     3  interfaces:
     4    - name: CompactOption
     5      comment: |
     6        CompactOption describes options that can be passed to `jws.Compact`
     7    - name: VerifyOption
     8      comment: |
     9        VerifyOption describes options that can be passed to `jws.Verify`
    10      methods:
    11        - verifyOption
    12        - parseOption
    13    - name: SignOption
    14      comment: |
    15        SignOption describes options that can be passed to `jws.Sign`
    16    - name: SignVerifyOption
    17      methods:
    18        - signOption
    19        - verifyOption
    20        - parseOption
    21      comment: |
    22        SignVerifyOption describes options that can be passed to either `jws.Verify` or `jws.Sign`
    23    - name: WithJSONSuboption
    24      concrete_type: withJSONSuboption
    25      comment: |
    26        JSONSuboption describes suboptions that can be passed to `jws.WithJSON()` option
    27    - name: WithKeySuboption
    28      comment: |
    29        WithKeySuboption describes option types that can be passed to the `jws.WithKey()`
    30        option.
    31    - name: WithKeySetSuboption
    32      comment: |
    33        WithKeySetSuboption is a suboption passed to the `jws.WithKeySet()` option
    34    - name: ParseOption
    35      methods:
    36        - readFileOption
    37      comment: |
    38        ReadFileOption is a type of `Option` that can be passed to `jwe.Parse`
    39    - name: ReadFileOption
    40      comment: |
    41        ReadFileOption is a type of `Option` that can be passed to `jws.ReadFile`
    42    - name: SignVerifyParseOption
    43      methods:
    44        - signOption
    45        - verifyOption
    46        - parseOption
    47        - readFileOption
    48  options:
    49    - ident: Key
    50      skip_option: true
    51    - ident: Serialization
    52      skip_option: true
    53    - ident: Serialization
    54      option_name: WithCompact
    55      interface: SignVerifyParseOption
    56      constant_value: fmtCompact
    57      comment: |
    58        WithCompact specifies that the result of `jws.Sign()` is serialized in
    59        compact format.
    60        
    61        By default `jws.Sign()` will opt to use compact format, so you usually
    62        do not need to specify this option other than to be explicit about it
    63    - ident: Detached
    64      interface: CompactOption
    65      argument_type: bool
    66      comment: |
    67        WithDetached specifies that the `jws.Message` should be serialized in
    68        JWS compact serialization with detached payload. The resulting octet
    69        sequence will not contain the payload section.
    70    - ident: DetachedPayload
    71      interface: SignVerifyOption
    72      argument_type: '[]byte'
    73      comment: |
    74         WithDetachedPayload can be used to both sign or verify a JWS message with a
    75         detached payload.
    76         
    77         When this option is used for `jws.Sign()`, the first parameter (normally the payload)
    78         must be set to `nil`.
    79         
    80         If you have to verify using this option, you should know exactly how and why this works.
    81    - ident: Message
    82      interface: VerifyOption
    83      argument_type: '*Message'
    84      comment: |
    85        WithMessage can be passed to Verify() to obtain the jws.Message upon
    86        a successful verification.
    87    - ident: KeyUsed
    88      interface: VerifyOption
    89      argument_type: 'interface{}'
    90      comment: |
    91        WithKeyUsed allows you to specify the `jws.Verify()` function to
    92        return the key used for verification. This may be useful when
    93        you specify multiple key sources or if you pass a `jwk.Set`
    94        and you want to know which key was successful at verifying the
    95        signature.
    96        
    97        `v` must be a pointer to an empty `interface{}`. Do not use
    98        `jwk.Key` here unless you are 100% sure that all keys that you
    99        have provided are instances of `jwk.Key` (remember that the
   100        jwx API allows users to specify a raw key such as *rsa.PublicKey)
   101    - ident: ValidateKey
   102      interface: SignVerifyOption
   103      argument_type: bool
   104      comment: |
   105        WithValidateKey specifies whether the key used for signing or verification
   106        should be validated before using. Note that this means calling
   107        `key.Validate()` on the key, which in turn means that your key
   108        must be a `jwk.Key` instance, or a key that can be converted to
   109        a `jwk.Key` by calling `jwk.FromRaw()`. This means that your
   110        custom hardware-backed keys will probably not work.
   111  
   112        You can directly call `key.Validate()` yourself if you need to
   113        mix keys that cannot be converted to `jwk.Key`.
   114  
   115        Please also note that use of this option will also result in
   116        one extra conversion of raw keys to a `jwk.Key` instance. If you
   117        care about shaving off as much as possible, consider using a
   118        pre-validated key instead of using this option to validate
   119        the key on-demand each time.
   120  
   121        By default, the key is not validated.
   122    - ident: InferAlgorithmFromKey
   123      interface: WithKeySetSuboption
   124      argument_type: bool
   125      comment: |
   126        WithInferAlgorithmFromKey specifies whether the JWS signing algorithm name
   127        should be inferred by looking at the provided key, in case the JWS
   128        message or the key does not have a proper `alg` header.
   129  
   130        When this option is set to true, a list of algorithm(s) that is compatible
   131        with the key type will be enumerated, and _ALL_ of them will be tried
   132        against the key/message pair. If any of them succeeds, the verification
   133        will be considered successful.
   134  
   135        Compared to providing explicit `alg` from the key this is slower, and 
   136        verification may fail to verify if somehow our heuristics are wrong
   137        or outdated.
   138        
   139        Also, automatic detection of signature verification methods are always
   140        more vulnerable for potential attack vectors.
   141        
   142        It is highly recommended that you fix your key to contain a proper `alg`
   143        header field instead of resorting to using this option, but sometimes
   144        it just needs to happen.
   145    - ident: UseDefault
   146      interface: WithKeySetSuboption
   147      argument_type: bool
   148      comment: |
   149        WithUseDefault specifies that if and only if a jwk.Key contains
   150        exactly one jwk.Key, that tkey should be used.
   151        (I think this should be removed)
   152    - ident: RequireKid
   153      interface: WithKeySetSuboption
   154      argument_type: bool
   155      comment: |
   156        WithRequiredKid specifies whether the keys in the jwk.Set should
   157        only be matched if the target JWS message's Key ID and the Key ID
   158        in the given key matches.
   159    - ident: MultipleKeysPerKeyID
   160      interface: WithKeySetSuboption
   161      argument_type: bool
   162      comment: |
   163        WithMultipleKeysPerKeyID specifies if we should expect multiple keys
   164        to match against a key ID. By default it is assumed that key IDs are
   165        unique, i.e. for a given key ID, the key set only contains a single
   166        key that has the matching ID. When this option is set to true,
   167        multiple keys that match the same key ID in the set can be tried.
   168    - ident: Pretty
   169      interface: WithJSONSuboption
   170      argument_type: bool
   171      comment: |
   172        WithPretty specifies whether the JSON output should be formatted and
   173        indented
   174    - ident: KeyProvider
   175      interface: VerifyOption
   176      argument_type: KeyProvider
   177    - ident: Context
   178      interface: VerifyOption
   179      argument_type: context.Context
   180    - ident: ProtectedHeaders
   181      interface: WithKeySuboption
   182      argument_type: Headers
   183      comment: |
   184        WithProtected is used with `jws.WithKey()` option when used with `jws.Sign()`
   185        to specify a protected header to be attached to the JWS signature.
   186        
   187        It has no effect if used when `jws.WithKey()` is passed to `jws.Verify()`
   188    - ident: PublicHeaders
   189      interface: WithKeySuboption
   190      argument_type: Headers
   191      comment: |
   192        WithPublic is used with `jws.WithKey()` option when used with `jws.Sign()`
   193        to specify a public header to be attached to the JWS signature.
   194        
   195        It has no effect if used when `jws.WithKey()` is passed to `jws.Verify()`
   196        
   197        `jws.Sign()` will result in an error if `jws.WithPublic()` is used
   198        and the serialization format is compact serialization.
   199    - ident: FS
   200      interface: ReadFileOption
   201      argument_type: fs.FS
   202      comment: |
   203        WithFS specifies the source `fs.FS` object to read the file from.